genstudio

Layerline GenStudio

Workflow for the AI generation side of Layerline — the GenStudio tools, plus the GDD and moodboard helpers that feed prompts.

The unified entrypoint: generate

Forget the legacy per-kind tools (create_generation_job, start_generation_step, etc.). Use generate:

generate(
  organizationId?,                    // optional with org-scoped API key
  kind,                               // see KINDS below
  projectId?,                         // required for auto-persist
  assetName?, assetTagName?, assetTagFolder?,  // all 3 → auto-persist
  assetId?,                           // alternative: attach result to existing asset
  prompt?,                            // for kinds that take text
  imageUrl?,                          // for image_to_*
  imageUrls?,                         // multiview (image_to_3d), max 8
  parentTaskId?,                      // for rig/animate/(texture chain)
  provider?,                          // adapter slug to lock to (e.g. "tripo")
  strategy?,                          // "balanced" (default) | "cheapest" | "fastest"
  config?,                            // adapter-specific passthrough
  wait?                               // default true; blocks up to 5 min
)

Kinds: image | image_to_image | image_to_3d | text_to_3d | texture | retopology | lod | rig | animate | audio_sfx.

Required combos:

• image, text_to_3d → require prompt.
• image_to_image, image_to_3d, texture (single-image variant) → require imageUrl (or imageUrls for multiview 3D).
• rig, animate → require parentTaskId (the upstream model task).

One-call generate-and-save

When you pass projectId + assetName + assetTagFolder together, success auto-creates a project asset and copies the generated files into LS. The response includes assetId, filesCopied, cloudFoldersCreated. This is the fast path for "generate and save as a new asset". Skip these args to get the raw task and persist later.

Wait vs. don't wait

• wait: true (default) — blocks up to 5 minutes. On timeout you still get the in-progress task back; poll get_generation_task to finish.
• wait: false — returns immediately with taskId and status: "queued". Poll get_generation_task yourself.

Use wait: false when the user explicitly wants async behavior or when running a multi-asset batch and you want to fire several in parallel.

Provider routing

Omit provider → the router picks one based on strategy. Set provider: "tripo" (or another slug) to force a specific adapter.

list_generation_adapters(kind?) shows what's currently wired. Adapters whose env vars are missing (e.g. TRIPO_API_KEY unset) report available: false and are skipped by the auto-router.

Polling, cancelling, history

get_generation_task(taskId, organizationId?)             // status, progress, step, result
cancel_generation(taskId, organizationId?)               // refunds reserved credits; idempotent
list_generations(organizationId?, provider?, status?, limit?, offset?)
get_generation_versions(taskId, organizationId?)         // root → latest in the version chain
get_generation_download_urls(taskId, organizationId?)    // presigned URLs for outputs (~1h TTL)

get_generation_download_urls is how you fetch the actual .glb / .png / .fbx bytes once a task succeeds.

The character pipeline

For multi-step character work in one call:

generate_character_pipeline(
  organizationId?,
  prompt? | imageUrl?,                     // need at least one (imageUrl skips concept)
  imageUrls?,                              // multiview for image_to_3d
  steps: { concept?, texture?, rig?, animate? },   // model is implicit
  projectId?, assetId?,
  providers?,                              // { model: "tripo", rig: "meshy", ... }
  config?                                  // per-step config map
)

Each step writes its own row in generation_tasks chained via parent_task_id. The leaf task id is what you stream to follow progress — its row updates as the chain advances.

Use this when the user wants the full "from text → rigged + animated character" path. For a one-shot single-kind job, prefer generate.

Prompt help

enhance_genstudio_prompt(idea, generationType?, contextHint?, organizationId?)

Expands a short user idea ("a knight") into a polished, production-ready prompt. Use it BEFORE generate when the user's prompt is terse — the result is meant for direct use in the next call. contextHint lets you bias toward a specific game type ("character concept for a stealth game", "isometric RTS prop").

Style presets

list_generation_styles(organizationId?, projectId?)
create_generation_style(name, promptModifier, settings?, referenceImageUrls?, organizationId?, projectId?)
delete_generation_style(styleId, organizationId?)

A style preset is a saved promptModifier + default settings combo (e.g. "Hand-painted PBR, low-poly stylized"). Apply via generate's config parameter — pass the style id or modifier through the adapter-specific config shape the user is targeting.

Game Design Documents (GDDs)

The GDD is the structured design document that owns a draft project — sections (Vision & Pillars, Overview, Characters, Art Direction, Mechanics) plus a fully linked asset + task graph. Use it as context for art direction when generating assets:

list_gdds(organizationId?, cursor?, limit?, status?, projectId?)
   // status: "draft" | "generating" | "review" | "converted"
get_gdd(gddId)                                  // full hydrate — game def + blocks + assets + tasks. Heavy.
export_gdd_json(gddId)                          // flat tagged JSON (vision, art_direction, characters, …). Lighter; better for prompt seeding.
get_gdd_asset(gddId, assetId)                   // single asset detail (versions, files, related tasks)
get_gdd_genstudio_context(assetId, gddId?)      // pre-fills name/desc/tags + suggested provider chain for an asset. Use BEFORE `generate`.

get_gdd returns a LOT. For narrow use ("just the art direction") prefer export_gdd_json and pull the section you need.

Moodboards

A moodboard is a canvas of reference images — used as visual style guidance for asset work. Tasks and projects can each have one.

get_task_moodboard(taskId)                          // get-or-create
get_task_moodboard_summary(taskId)                  // lightweight
get_project_moodboard(projectId)
get_moodboard(moodboardId)
get_moodboard_reference_url(moodboardId, referenceId, thumbnail?, expiresInSeconds?)

create_moodboard(taskId? | projectId?, name?)
update_moodboard_reference(moodboardId, referenceId, positionX?, positionY?, scaleX?, scaleY?, rotation?, notes?)
remove_moodboard_reference(moodboardId, referenceId)
restore_moodboard_reference(moodboardId, referenceId)
clear_moodboard(moodboardId)                        // permanent delete

get_moodboard_reference_url returns a presigned URL — use it when you want the agent to actually SEE a reference image (for inspecting style), or to feed it to a 2D image_to_image job.

There is no upload tool for moodboard refs via MCP. Users add references through the desktop/web client.

Common workflows

"Generate a hero knight character and save it as an asset"

1. Resolve projectId.
2. enhance_genstudio_prompt(idea="hero knight, fantasy, hand-painted") → polished prompt.
3. generate(kind="image_to_3d", prompt=<enhanced>, imageUrl=<concept image>, projectId, assetName="Hero Knight", assetTagName="Characters", assetTagFolder="Characters", strategy="balanced").
4. Response includes assetId — tell the user the asset was created.

If they want concept → model → texture → rig in one call, use generate_character_pipeline with steps: { concept: true, texture: true, rig: true } instead.

"Just generate me 4 concept images of a volcano"

1. generate(kind="image", prompt="pixel-art volcano, top-down, lava cracks", config={ count: 4 }, wait: false) — fire async.
2. get_generation_task(taskId) to check progress.
3. get_generation_download_urls(taskId) once succeeded.

"What's the art direction for project X?"

1. list_gdds(projectId=...) → find the GDD.
2. export_gdd_json(gddId) → pull the art_direction section.

"Generate a new character matching the GDD's art style"

1. Find the GDD asset (list_gdds, get_gdd).
2. get_gdd_genstudio_context(assetId, gddId) — returns suggested provider, prompt context, gameDefId.
3. Use the returned context to seed generate (it pre-fills name, description, tags, provider chain).

"Show me the moodboard refs for task Y"

1. Resolve taskId.
2. get_task_moodboard(taskId) → returns the moodboard with active references.
3. For each ref the agent needs to actually SEE, get_moodboard_reference_url(moodboardId, referenceId).

Hard-won rules

• Don't omit assetTagName if you want auto-persist. The auto-persist trigger is projectId + assetName + assetTagFolder, but the tag name defaults to the folder name only when assetTagName is missing — pass both for clarity.
• Don't poll get_generation_task faster than ~5 seconds. Status updates are debounced.
• Cancellations refund credits. If you hit wait timeout and the job is genuinely stuck, cancel_generation is the safe call.
• imageUrl must be reachable by the generation worker — a presigned LS URL works (ls_get_download_url). A localhost URL or unsigned blob will fail.
• If a kind isn't accepted, check list_generation_adapters(kind) — some kinds depend on adapters whose API keys aren't configured in this environment.

Pairings

• Persisted asset shows up in list_assets — see layerline:assets to comment, change status, link tasks.
• Generation outputs are LS files — use layerline:storage to attach to other entities, share, or version.
• The result probably needs review before shipping — see layerline:reviews to open a review on the new asset.