higgsfield-game-generation

SKILL.md

Higgsfield Game Generation

Create a coherent, playable web game and deliver the URL, or produce only the requested game assets. Higgsfield CLI owns generation, 3D action discovery, deployment, and optional marketplace publication.

Bootstrap

Before work begins:

If higgsfield is unavailable, install it:
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

If higgsfield account status reports an expired or missing session, ask the user to run higgsfield auth login, then continue after confirmation.

For a full game, confirm higgsfield game deploy --help works before generating assets. This is the delivery capability check.

Locate this installed skill directory and set it explicitly:
export GAME_SKILL="/absolute/path/to/higgsfield-game-generation"
test -f "$GAME_SKILL/scripts/pipeline.py"
python3 "$GAME_SKILL/scripts/pipeline.py" --help

Never recreate bundled scripts from memory.

Route the request

Full playable game — follow the full workflow below.

Assets only — read references/stylization.md, then the matching asset reference. Do not deploy a game.

Design only — read references/game-design-system.md; return the requested design artifact and asset manifest.

Existing game iteration — inspect the supplied source, preserve its architecture and unchanged assets, amend the manifest, rebuild, verify, and redeploy with its existing game ID.

Trailer or promotional video — use higgsfield-generate, not this skill.

Native mobile/desktop/console runtime — explain that this skill ships browser games; offer a web build unless the user supplied another toolchain.

Full game workflow

1. Plan

Read references/game-design-system.md first and in full. Resolve the game profile, delivery context, core loop, win/lose/restart behavior, performance budgets, input methods, and language handling.

Create design/assets.csv with one row per visual or audio asset:

id,role,type,description,size/ratio,style line ref,source

Read references/multiplayer.md whenever Players is not solo. Local same-screen multiplayer remains client-side; online multiplayer requires the platform server module.

Read references/stylization.md before producing any visual, including procedural canvas art. Derive one STYLE FORMULA and insert it byte-for-byte into every visual prompt. If the brief already fixes the style, state the formula and continue. If several materially different styles fit, show concise options and wait for selection.

No game code or generated visual should exist before the manifest and STYLE FORMULA.

2. Generate assets and build

Start independent generation jobs together, then write the game while those jobs run. Inspect every model contract before first use:

higgsfield model list --json
higgsfield model get <job_type>
higgsfield generate create <job_type> ... --wait --json

Media flags accept local paths or prior upload/job IDs. Keep job JSON in project files when chaining; do not dump IDs into the user-facing reply.

Read the reference matching each manifest row:

Asset
Required reference

Static sprites, backgrounds, UI
references/stylization.md

Spritesheets / 2D animation
references/2d-animation.md

Repeating ground, walls, tiles, PBR maps
references/textures.md

Any 3D model or animation
references/3d-animation.md

Music, SFX, voice
references/audio.md

For 3D animation selection:

higgsfield preset list animation-action --query walk --json
higgsfield preset list animation-action --group Fighting --category Punching --json

When multiple actions fit, show their preview URLs and let the user choose. Pass the chosen integer as --animation_action_id only after checking the target model schema.

Read references/build-game.md last, but before writing game code. Assemble the source ZIP with index.html and exactly one root code module (logic.js or server.js). Use relative asset paths and keep design/assets.csv in the shipped project.

Generation failures get at most two retries. After that, use the best valid result and compensate in code, or amend the manifest honestly.

3. Verify and deliver

Run the local game over HTTP, not file://:

python3 -m http.server 8000

Verify the complete loop, restart, missing assets, console errors, responsive canvas, non-Latin keyboard layout through event.code, touch-only play when mobile is in scope, declared gamepad controls, fixed-timestep behavior, and multiplayer in two sessions when applicable.

Package from the directory that contains the required root files:

zip -r /absolute/path/to/game.zip . -x '*.DS_Store' 'node_modules/*' '.git/*'
higgsfield game deploy /absolute/path/to/game.zip \
  --title "<public title>" \
  --description "<player-facing description>" \
  --thumbnail "<optional https 16:9 image URL>" \
  --favicon "<optional https 1:1 image URL>" \
  --json

For an update, add --game-id <existing_game_id>; never omit it after an update failure, because that would create a different game.

Deployment creates the playable URL. Publishing to the public marketplace is a separate external action and requires explicit user intent:

higgsfield game publish <game_id> \
  --name "<optional listing name>" \
  --description "<optional listing description>" \
  --cover-url "<optional https 16:9 URL>" \
  --logo-url "<optional https 1:1 URL>" \
  --json

Re-open the returned playable URL and repeat the critical smoke path. Deliver the URL returned by CLI; never construct it manually.

Reference order

For full games:

references/game-design-system.md

references/multiplayer.md when Players is not solo

references/stylization.md

Conditional asset references

references/build-game.md

Read each selected reference completely. Do not load unrelated references.

Supporting references opened only when their owning route requires them:

references/client-reference.md — online client protocol.

references/kernel-reference.md — platform room-kernel contract.

references/logic-reference.md — turn-based/event-driven rules module.

references/meshy-api.md — raw Meshy fallback only.

references/meshy-input-rules.md — mandatory before any image-to-3D submit.

references/procedural-animation.md — non-humanoid procedural rigs.

UX rules

Mirror the user's language; keep generation prompts in English.

User updates are short and describe the game, not internal gates, phase numbers, job IDs, or tool mechanics.

Ask only when the answer materially changes the game. Do not batch unrelated questions.

Preserve one visual system across generated and procedural assets.

Do not request secrets in chat. Raw Meshy fallback may use a user-configured environment key only when the native Higgsfield 3D model is unavailable.

Do not publish publicly unless the user requested marketplace publication.

Output

Design-only: requested design artifact plus design/assets.csv.

Assets-only: usable files/result URLs and their manifest roles.

Full game: verified playable URL, a one-line gameplay summary, and marketplace URL only when explicitly published.