PromptMotion

This document covers both tools. Generator-specific topics are grouped under Generator; Library-specific topics under Library. Sections that apply to both live under Concepts and Reference.

⤓ Installation

Import once. Both tools light up immediately.

From the Unity Asset Store

Prerequisites

PromptMotion uses two Unity packages that ship with a default Unity 6 install:

• com.unity.editorcoroutines ≥ 1.0.0
• com.unity.nuget.newtonsoft-json ≥ 3.2.1

If your project doesn't already have Newtonsoft.Json, Unity prompts to add it on first import. Click Yes.

What gets installed

Assets/PromptMotion/
  Generator/                  // AI generator window + auth + HTTP
    Editor/
  Library/                    // Bundled clip browser + 5 starter clips
    Editor/
    StarterClips/             // .anim files retargetable to any Humanoid
  Shared/                     // ClipApplier, Avatar validators, Preview viewport
  Generated/                  // Output folder created on first generation
    Controllers/              // Per-character AnimatorControllers
  Documentation/              // You are hereProject

⚡ Quick Start: Generator

Zero to your first generated clip in about a minute (plus generation time).

☷ Quick Start: Library

No invoice. No internet. No waiting.

The drag-and-drop path

The Animation Library window

For browsing more than a handful of clips, the dedicated window provides a Mixamo-style three-pane layout:

Drop your character into the slot once; click any clip card to preview it on your rig; click Apply to wire it into the controller.

⚙ How It Works

A single round-trip from the Editor to the PromptMotion backend.

1. You type a prompt and click ⚡ Generate.
2. The window posts { prompt, duration_seconds, seed } to https://api.promptmotion.dev/prod/generate with your invoice as authentication.
3. The backend runs the prompt through NVIDIA's Kimodo (SOMA-RP) text-to-motion model.
4. The raw motion is retargeted to a standard Humanoid skeleton on the server.
5. The server returns a Mecanim-ready .fbx file.
6. The client saves the FBX under Assets/PromptMotion/Generated/. An AssetPostprocessor auto-configures it as Animation Type: Humanoid.
7. The window applies the resulting AnimationClip to your selected character via ClipApplier.

You don't need to know anything about Kimodo, retargeting, or import settings — the pipeline is fully automated. The output is a standard Unity AnimationClip; you can edit, blend, retarget, mask, or layer it like any other clip.

🔒 Activation

Your Unity Asset Store invoice number activates the asset. No signup, no API key.

How activation works

Click Verify in the Generator window after pasting your invoice. The window confirms with the server that the invoice is valid. The whole process takes a few seconds.

Working across multiple installations

Your invoice activates the asset across all your installations. Paste your invoice number anywhere you've installed PromptMotion and it will work — quota is shared across installations.

Forgetting an invoice

Open Window → PromptMotion → Settings and click Forget invoice to clear your locally stored invoice. You can paste it again any time.

What gets sent to the server

Only this:

• Your invoice number (HTTPS, in the JSON body).
• The prompt text you typed.
• Duration and optional seed.
• A client version string.

Not sent: real name, email, IP (other than what's inherent to HTTPS), Unity Editor analytics, scene contents, or any telemetry beyond the above.

⏲ Monthly Allowance

50 generations per month included. Cached prompts use none of your allowance.

How the allowance works

Every successful generation uses one of your 50 monthly generations. Cached results — identical (prompt, duration, seed) — do not count against your allowance. Your next allowance is issued automatically each month.

The Ready banner shows your remaining count, for example: 47 of 50 generations remaining this month. Next allowance arrives in 12 days.

What happens when the monthly limit is reached

• The status banner indicates the monthly limit is reached.
• The window shows when your next allowance arrives.
• Existing generations and cached prompts continue to work — only new generations are paused until the next allowance.
• You can keep working with the bundled Library clips, which use none of your allowance.

✏ Writing Prompts

Describe the motion. The model never sees your character.

Prompts that work well

• "walking forward confidently"
• "running and jumping over a low obstacle"
• "sitting down on a chair, then standing back up"
• "waving hello with the right hand"
• "stumbling backwards as if pushed"
• "crouching slowly, then aiming a bow"

Prompts that work less well

• Character descriptions — "a tall warrior": ignored. The model sees motion verbs only.
• Camera or shot direction — "close-up of feet": output is a clip, not a render.
• Multi-character interactions — "two people fighting": output is one humanoid.
• Specific timing — "walk for 1.7 s, then turn": duration is set by the slider; phasing is approximate.

Current model limitations

Duration & seed

Duration: integer between 1 and 10 seconds. Longer clips take slightly longer to generate but use the same single generation from your allowance.

Seed: leave blank to let the server randomize. Set a specific integer to make the output reproducible — same prompt + same duration + same seed = same FBX (and a cache hit).

🧍 Character Requirements

Both tools require a Humanoid rig. Generic skeletons aren't supported in v1.0.

What "Humanoid" means here

• The character has an Animator component.
• Its Avatar is configured with Animation Type = Humanoid (Import Settings → Rig tab).
• Unity reports the Avatar as valid (no broken bone mappings).

Validator badges

Drop a character into the slot and the window checks:

T-pose preferred

Characters configured from a clean T-pose retarget cleanest. A-pose works but may produce slight shoulder offset on extreme clips. Bind-pose-flopped rigs (one arm forward) often produce wrong shoulder rotation — re-import in T-pose if you see shoulders pop.

📁 Generated Files

Where things land, how they're named, what else gets created.

Output location

Every generated FBX lands in:

Assets/PromptMotion/Generated/Path

Naming convention

Each filename embeds the backend's job id, e.g. job_a8f3c1e9.fbx. The job id is unique per generation; cache hits return the same file rather than producing a duplicate.

What gets created besides the FBX

• The FBX at Assets/PromptMotion/Generated/{job_id}.fbx, auto-imported as Humanoid.
• An Animator Controller at Assets/PromptMotion/Generated/Controllers/{character}_Controller.controller, one per character. Re-applying clips to the same character updates this same file.

Regenerating with the same prompt

If the cache key matches, no new file is created — the existing FBX is returned. If the seed changes (or you click Random), a fresh FBX is written under a new job id; both files coexist.

🔧 Settings

A single ScriptableObject configures the Generator. No secrets, safe to commit.

Settings live as a ScriptableObject at Assets/PromptMotion/Generator/Editor/Settings/Settings.asset. Select it in the Project window to edit in the Inspector.

Your invoice number is stored separately in EditorPrefs (base64'd, XOR-obfuscated) and is never written to an asset.

☷ Library: Overview

Pre-baked humanoid clips, bundled. Offline, instant, free.

The Library is a small set of pre-generated humanoid clips bundled directly inside the asset. They ship as standard Unity AnimationClip assets that retarget to any Humanoid character — no backend, no internet, no quota.

Why a Library at all, when the Generator exists?

The Library and the Generator share the same Humanoid Avatar foundation, the same ClipApplier, and the same auto-import behaviour. A clip from the Library and a clip from the Generator are interchangeable in your AnimatorController.

♬ Library: Clips Included

Five hand-picked starter clips covering common motions.

Each clip was generated by the Generator, manually reviewed, and curated to demonstrate the kinds of output you can expect. All five are configured for Humanoid retargeting and ship as standalone .anim files at Assets/PromptMotion/Library/StarterClips/.

➤ Library: How to Use

Three equivalent ways to get a Library clip onto a character.

Option 1 — Drag onto an Animator

In the Project window, drag any .anim from Assets/PromptMotion/Library/StarterClips/ onto a Humanoid GameObject in the Hierarchy. Unity auto-creates an Animator Controller (if absent) and adds the clip as the default state.

Option 2 — Drop into an existing AnimatorController

Open an AnimatorController, drag the clip onto the graph to create a new state, then wire transitions as usual. Useful when integrating into an existing state machine.

Option 3 — Use the Animation Library window

Window → PromptMotion → Animation Library. Drop your character into the slot, click any clip card to preview it on your rig, then click Apply to wire it into the controller. The window handles prefab vs scene-instance distinctions, controller lookup, and idempotent state updates for you.

Option 4 — Animation window

Select the character, open Window → Animation → Animation, and drag the clip into its track list. Useful when you're authoring a Timeline.

✂ Library: Customizing Clips

Library clips are standard Unity AnimationClips. Anything goes.

Anything you can do to a hand-authored clip, you can do to a Library clip:

• Edit curves in Window → Animation → Animation.
• Change loop behaviour, root motion, cycle offset in the clip's Inspector.
• Apply Avatar Masks for layered animation (e.g. upper-body sword swing while lower body keeps walking).
• Blend between clips in a BlendTree.
• Mix into a Timeline.
• Retarget by virtue of Humanoid — the same clip works on Mixamo X Bot, a Synty character, your own rig.

🏆 Library: Why Bundle Both

Generator and Library cover different needs.

The Library is the safety net. The Generator is the workhorse. You'll mostly reach for the Generator once you're set up — the Library is what makes the asset functional in evaluation mode, in offline scenarios, and as a quality preview before purchase.

🧍 Humanoid Avatar System

Why the asset is Humanoid-only, and how to fix Generic-rig issues.

Both tools rely on Unity's Humanoid Avatar system to retarget a generic skeleton onto whatever character you provide. A few things worth knowing:

Why Humanoid and not Generic

Humanoid is a normalized rig: Unity maps any compatible skeleton to its standard 15 bones (hips, spine, chest, neck, head, shoulders, upper/lower arms, hands, upper/lower legs, feet). A clip authored on a normalized rig retargets to any Humanoid character without manual bone mapping. Generic clips are tied to the source skeleton and don't transfer cleanly.

What Unity needs from your rig

• A skeleton with bones named in any pattern Unity recognises (most do, including Mixamo, Synty, Quaternius, and most CC-licensed rigs).
• Animation Type set to Humanoid in the model's Import Settings — Rig tab.
• An Avatar sub-asset embedded in the FBX (Unity creates this when you switch to Humanoid).
• An Animator component on the character GameObject with the Avatar slot filled.

Generic-rig fix

If your character imports as Generic by default and PromptMotion rejects it, re-import:

⟳ Auto-Import Pipeline

An AssetPostprocessor configures every Generated FBX so you don't have to.

What MotionFbxPostprocessor does

For every FBX under Assets/PromptMotion/Generated/:

• Sets Animation Type = Humanoid.
• Sets Avatar Definition = Create From This Model.
• Disables mesh, material, camera, and light import (the file is animation-only).
• Preserves the bone hierarchy as-is.
• Logs the configuration to the Console when Verbose Logging is on.

Files outside Generated/ are not touched — your own model imports are left alone.

Opting out

If you want a Generated FBX to use different import settings, move it out of the Generated folder. The postprocessor only fires on first import and on re-import — once a file is moved elsewhere, the standard Unity Import Settings panel takes over.

✔ Apply to Character

From "I have an AnimationClip" to "the clip is wired into a controller."

ClipApplier handles everything from clip-in-hand to clip-on-character. It's used by both the Generator (after generation) and the Library (when you click Apply).

Three cases handled identically

• Prefab asset — the prefab in the Project window is opened with PrefabUtility.LoadPrefabContents, edited, then saved with SaveAsPrefabAsset.
• Prefab instance in a scene — modifications are recorded with Undo.RecordObject so they're persisted on the instance.
• Plain scene GameObject — the scene object is edited directly.

What gets created

Idempotent

Re-applying the same clip updates the existing state rather than duplicating it. Apply a different clip and a new state is added without disturbing the others.

When auto-apply fails

If the selection isn't a Humanoid character or doesn't have a SkinnedMeshRenderer the validator can find an Avatar from, the window shows a HelpBox with the saved FBX path and instructions to drag the clip in manually. The FBX is on disk either way — auto-apply is just a convenience.

💡 Troubleshooting

Every error code, what it means, and how to recover.

The Generator window shows a status banner with a code-mapped message and a recovery button whenever something goes wrong. Twelve codes total — ten reported by the server, two emitted client-side.

Server-reported codes

Client-side codes

Common issues

Network checklist

If you're behind a corporate firewall, whitelist:

• https://api.promptmotion.dev (HTTPS, port 443) — the production backend.
• Any CDN your firewall flags during the FBX download response — the file is served by the same domain.

The asset uses Unity's standard UnityWebRequest, which respects your system proxy. No custom protocols, no WebSocket, no peer-to-peer.

❓ FAQ

Quick answers to the questions that come up most.

📬 Support

Need help? We're here for you.