AI Docs
React Example: Generate Motion GitHub
import { useState } from 'react'
import { createFileRoute } from '@tanstack/react-router'
import { fetchServerSentEvents, useGeneration } from '@tanstack/ai-react'
import { falByok } from '@tanstack/ai-fal/byok'
import type { MotionGenerationResult, MotionStatusResult } from '@tanstack/ai'
import { FalKeyForm } from '@/components/fal-key-form'
import { byok } from '@/lib/byok'
const CLIP_SECONDS = 4
const ATTACKER_PROMPT =
'A heavy orc warrior leaps forward, raises a two-handed axe overhead, slams it down into the ground, and lands with a heavy stagger'
const REACTION_PROMPT =
'A person is hit hard from the front, staggers backward, falls onto their back, then slowly gets up'
// A designer sets this after previewing the attacker clip. fal does not
// return contact timing, so the game owns this number, not the provider.
const IMPACT_TIME_SECONDS = 1.6
type MotionInput = { prompt: string; duration: number }
function hasJobId(value: unknown): value is { jobId: string } {
return (
typeof value === 'object' &&
value !== null &&
'jobId' in value &&
typeof value.jobId === 'string'
)
}
function isMotionStatus(value: unknown): value is MotionStatusResult {
return (
hasJobId(value) && 'status' in value && typeof value.status === 'string'
)
}
// One generation slot. The hook streams the job from /api/generate/motion.
// onChunk reads the fal job id and the queue status from CUSTOM events.
function useMotionClip(threadId: string) {
const [jobId, setJobId] = useState<string | null>(null)
const [jobStatus, setJobStatus] = useState<MotionStatusResult | null>(null)
const [stopped, setStopped] = useState(false)
const generation = useGeneration<MotionInput, MotionGenerationResult>({
connection: fetchServerSentEvents('/api/generate/motion'),
threadId,
byok,
onChunk: (chunk) => {
if (chunk.type !== 'CUSTOM') return
if (chunk.name === 'motion:job:created' && hasJobId(chunk.value)) {
setJobId(chunk.value.jobId)
}
if (chunk.name === 'motion:status' && isMotionStatus(chunk.value)) {
setJobStatus(chunk.value)
}
},
})
return {
...generation,
jobId,
jobStatus,
stopped,
generate: (input: MotionInput) => {
generation.reset()
setJobId(null)
setJobStatus(null)
setStopped(false)
return generation.generate(input)
},
// stop() closes the stream in this tab. The fal job keeps running.
stop: () => {
generation.stop()
setStopped(true)
},
}
}
type MotionClip = ReturnType<typeof useMotionClip>
function describeJob(status: MotionStatusResult) {
switch (status.status) {
case 'pending':
return status.queuePosition === undefined
? 'Queued on fal'
: `Queued on fal, position ${status.queuePosition}`
case 'processing':
return 'Generating'
case 'completed':
return 'Finished on fal, fetching files'
case 'failed':
return `Failed: ${status.error ?? 'fal gave no reason'}`
}
}
function describeClip(clip: MotionClip) {
if (clip.error) return `Error: ${clip.error.message}`
if (clip.result) return 'Done'
if (clip.stopped) return 'Stopped watching. The fal job keeps running.'
if (clip.jobStatus) return describeJob(clip.jobStatus)
if (clip.isLoading) return 'Submitting'
return 'Not started'
}
function fbxUrl(motion: MotionGenerationResult) {
return motion.assets.find((asset) => asset.format === 'fbx')?.url ?? null
}
// The JSON a game imports. Clips come from fal. Timing and effects are yours.
function buildManifest(
attacker: MotionGenerationResult,
reaction: MotionGenerationResult,
) {
return {
ability: 'orc-leap-slam',
attacker: {
clip: fbxUrl(attacker),
source: attacker.model,
jobId: attacker.jobId,
seed: attacker.seed ?? null,
},
reactions: [{ clip: fbxUrl(reaction), trigger: 'impact' }],
events: [
{
name: 'impact',
timeSeconds: IMPACT_TIME_SECONDS,
source: 'authored',
note: 'Set by a designer after previewing the clip. The provider does not return contact timing.',
},
],
effects: ['shockwave', 'dust', 'ground-cracks', 'flying-rocks'],
}
}
async function cancelOnFal(jobId: string) {
const response = await fetch('/api/motion/cancel', {
method: 'POST',
headers: {
'content-type': 'application/json',
...byok.headers(falByok.id),
},
body: JSON.stringify({ jobId }),
})
if (!response.ok) throw new Error(await response.text())
}
function ClipPanel({
id,
title,
clip,
prompt,
onPromptChange,
}: {
id: string
title: string
clip: MotionClip
prompt: string
onPromptChange: (prompt: string) => void
}) {
const [cancelNote, setCancelNote] = useState('')
const { jobId } = clip
const handleCancel = () => {
if (!jobId) return
setCancelNote('Asking fal to cancel...')
void cancelOnFal(jobId)
.then(() =>
setCancelNote(
'fal accepted the cancel. A running job can still finish.',
),
)
.catch((caught: unknown) =>
setCancelNote(
caught instanceof Error ? caught.message : 'Cancel failed',
),
)
}
return (
<section className="flex flex-col gap-3 rounded-lg border border-orange-500/20 bg-gray-800 p-4">
<h2 className="text-lg font-semibold text-white">{title}</h2>
<label htmlFor={id} className="text-sm text-gray-300">
Prompt ({CLIP_SECONDS} second clip)
</label>
<textarea
id={id}
value={prompt}
onChange={(event) => onPromptChange(event.target.value)}
rows={4}
disabled={clip.isLoading}
className="w-full resize-none rounded-lg border border-orange-500/20 bg-gray-900 px-3 py-2 text-sm text-white focus:outline-none focus:ring-2 focus:ring-orange-500/50"
/>
<div className="flex flex-wrap gap-2">
<button
type="button"
onClick={() =>
void clip.generate({
prompt: prompt.trim(),
duration: CLIP_SECONDS,
})
}
disabled={!prompt.trim() || clip.isLoading}
className="rounded-lg bg-orange-500 px-3 py-2 text-sm font-medium text-white disabled:opacity-50"
>
Generate
</button>
<button
type="button"
onClick={clip.stop}
disabled={!clip.isLoading}
className="rounded-lg border border-gray-600 px-3 py-2 text-sm text-gray-200 disabled:opacity-50"
>
Stop watching
</button>
<button
type="button"
onClick={handleCancel}
disabled={!jobId || Boolean(clip.result)}
className="rounded-lg border border-red-500/40 px-3 py-2 text-sm text-red-300 disabled:opacity-50"
>
Cancel on fal
</button>
</div>
<p className="text-sm text-gray-300" aria-live="polite">
Status: {describeClip(clip)}
</p>
{jobId ? <p className="text-xs text-gray-500">fal job: {jobId}</p> : null}
{cancelNote ? (
<p className="text-xs text-amber-400">{cancelNote}</p>
) : null}
{clip.result ? (
<div className="flex flex-col gap-2">
<ul className="flex flex-col gap-1 text-sm">
{clip.result.assets.map((asset) => (
<li key={asset.url}>
<a
href={asset.url}
download={asset.fileName}
target="_blank"
rel="noreferrer"
className="text-orange-400 underline"
>
Download {asset.fileName ?? asset.format}
</a>{' '}
<span className="text-gray-400">
({asset.format.toUpperCase()}
{asset.fileSize === undefined
? ''
: `, ${Math.round(asset.fileSize / 1024)} KB`}
)
</span>
</li>
))}
</ul>
<p className="text-xs text-gray-400">
fal file links expire. Download the file and store it with your game
assets.
</p>
</div>
) : null}
</section>
)
}
function LeapSlamPage() {
const [attackerPrompt, setAttackerPrompt] = useState(ATTACKER_PROMPT)
const [reactionPrompt, setReactionPrompt] = useState(REACTION_PROMPT)
const attacker = useMotionClip('orc-leap-slam')
const reaction = useMotionClip('enemy-knockdown')
const manifest =
attacker.result && reaction.result
? buildManifest(attacker.result, reaction.result)
: null
return (
<div className="min-h-screen bg-gray-900">
<div className="border-b border-orange-500/20 bg-gray-800 px-4 py-3">
<FalKeyForm />
</div>
<main className="mx-auto flex max-w-5xl flex-col gap-6 px-4 py-8">
<div>
<h1 className="mb-2 text-2xl font-semibold text-white">
Orc chieftain: Leap Slam
</h1>
<p className="text-sm text-gray-400">
Generate the attacker clip and the enemy reaction clip. Each one is
an FBX file from fal Hunyuan Motion.
</p>
</div>
<div className="grid gap-4 md:grid-cols-2">
<ClipPanel
id="attacker-prompt"
title="Attacker: orc leap slam"
clip={attacker}
prompt={attackerPrompt}
onPromptChange={setAttackerPrompt}
/>
<ClipPanel
id="reaction-prompt"
title="Reaction: enemy knockdown"
clip={reaction}
prompt={reactionPrompt}
onPromptChange={setReactionPrompt}
/>
</div>
<section className="flex flex-col gap-3 rounded-lg border border-orange-500/20 bg-gray-800 p-4">
<h2 className="text-lg font-semibold text-white">Ability manifest</h2>
{manifest ? (
<pre className="overflow-x-auto rounded-lg bg-gray-900 p-3 text-xs text-gray-200">
{JSON.stringify(manifest, null, 2)}
</pre>
) : (
<p className="text-sm text-gray-400">
Generate both clips to see the manifest.
</p>
)}
<p className="text-sm text-gray-400">
Your engine (for example Unity) does the rest. It retargets the
clips to your rig, attaches the axe, and blends the clips. When the
impact event fires, it applies damage, plays the reaction, and
spawns the effects.
</p>
</section>
</main>
</div>
)
}
export const Route = createFileRoute('/')({
component: LeapSlamPage,
})