Hot-Swap a 3D Avatar Without Publishing the Broken Frame

A developer has published a tutorial for building a two-phase, transactional avatar loader that keeps the currently committed 3D avatar visible until a newly generated candidate passes policy validation and runtime qualification. The controller wraps Tencent RTC's Beauty AR SDK through a narrow adapter, using per-device-tier thresholds for declared asset size, qualification frames, bad-frame tolerance, and frame time, and deliberately avoids revealing the camera when no avatar has been committed. The implementation has no rendering-library dependency, making its state and failure behavior testable without a camera, GPU, or live room.

An AI tool can help generate a 3D avatar concept, asset manifest, or integration scaffold in minutes. The uncomfortable part begins afterward: who decides that the candidate is safe to show in a live session? A model can produce something visually persuasive without proving that it loads on the target device, tracks correctly, stays within your rendering budget, or survives a failed wardrobe change. That does not make AI-assisted creation useless. It changes the engineering task. Instead of treating “the asset exists” as completion, we need a controlled transition from a candidate avatar to the avatar participants actually see . In this tutorial, we will build that transition as a two-phase loader: Tencent RTC Beauty AR supports scenarios including avatars, beauty effects, stickers, virtual backgrounds, and image or video enhancement. The official overview is here: https://trtc.io/document/beauty-ar-overview https://trtc.io/document/beauty-ar-overview The controller below deliberately sits around the selected Beauty AR SDK integration. It does not invent SDK methods. You map its narrow adapter to the APIs and platform described by the official documentation. Suppose a user is already represented by avatar-blue-v4 and selects a newly generated 3D avatar. The tempting implementation is: await loadAvatar nextAsset ; showAvatar nextAsset ; That leaves several questions unanswered: Our invariant is stronger: The committed avatar remains visible until a newer candidate has passed policy validation and runtime qualification. If no avatar has been committed, the application should show an explicit placeholder or paused-avatar state. It should not silently reveal the camera; camera presentation requires its own product policy and consent decision. mkdir transactional-avatar-loader cd transactional-avatar-loader npm init -y npm install --save-dev typescript vitest @types/node npx tsc --init mkdir src Add the test script to package.json : { "scripts": { "test": "vitest run" } } The implementation has no rendering-library dependency. That makes its state and failure behavior testable without a camera, GPU, or live room. Create src/avatar-loader.ts : export type DeviceTier = "low" | "mid" | "high"; export interface AvatarManifest { id: string; revision: string; format: "3d-avatar"; declaredBytes: number; } export interface PreparedAvatar { assetId: string; revision: string; opaqueHandle: unknown; } export interface FrameProbe { rendered: boolean; tracking: "good" | "lost"; frameTimeMs: number; } export interface TierPolicy { allow3dAvatar: boolean; maxDeclaredBytes: number; qualificationFrames: number; maxBadFrames: number; maxFrameTimeMs: number; } export type PolicyByTier = Record<DeviceTier, TierPolicy ; These thresholds belong to the application, not to Tencent RTC and not to an AI asset generator. They should be selected from measurements on devices your product supports. A starter configuration might look like this: js export const examplePolicy: PolicyByTier = { low: { allow3dAvatar: false, maxDeclaredBytes: 0, qualificationFrames: 0, maxBadFrames: 0, maxFrameTimeMs: 0 }, mid: { allow3dAvatar: true, maxDeclaredBytes: 8 000 000, qualificationFrames: 12, maxBadFrames: 2, maxFrameTimeMs: 40 }, high: { allow3dAvatar: true, maxDeclaredBytes: 16 000 000, qualificationFrames: 12, maxBadFrames: 1, maxFrameTimeMs: 32 } }; Those numbers are illustrative acceptance values, not product benchmarks or universal device limits . Replace them with thresholds derived from your own device matrix. Tencent RTC's low-end device optimization guide recommends adapting effects by device tier and avoiding expensive capabilities such as 3D, GAN effects, or segmentation when the device cannot sustain them. It also discusses controlling resolution, frame rate, and performance modes: https://trtc.io/document/66968 https://trtc.io/document/66968 The important product decision is that allow3dAvatar: false means “do not attempt this workload,” not “try it and hope users tolerate the result.” Continue in the same file: export interface AvatarPort { prepare manifest: AvatarManifest : Promise<PreparedAvatar ; probe candidate: PreparedAvatar : Promise<FrameProbe ; // Keep this operation synchronous at the controller boundary. activate candidate: PreparedAvatar : void; restore previous: PreparedAvatar | null : void; dispose candidate: PreparedAvatar : Promise<void ; } prepare can download, decode, and initialize resources in a hidden or off-screen context. probe asks the integration for application-level observations about candidate output. The activate boundary is intentionally synchronous. JavaScript cannot interleave another selection in the middle of a synchronous commit, so an old asynchronous completion cannot win after the final version check. If the platform-specific activation API is asynchronous, the adapter must provide equivalent serialization or transaction semantics. Do not simply change this method to return a promise without reconsidering the race: a newer user selection could arrive while the older candidate is being made visible. export type LoaderState = | { tag: "showing"; avatarId: string | null; warning?: string } | { tag: "preparing"; candidateId: string; stillShowing: string | null } | { tag: "qualifying"; candidateId: string; stillShowing: string | null } | { tag: "committing"; candidateId: string; stillShowing: string | null } | { tag: "failed"; candidateId: string; stillShowing: string | null; reason: string; }; export type SwitchResult = | { ok: true; avatarId: string } | { ok: false; reason: string; superseded?: boolean }; This state is useful beyond the renderer: Now implement the controller: export class AvatarLoader { private operation = 0; private current: PreparedAvatar | null = null; public state: LoaderState = { tag: "showing", avatarId: null }; constructor private readonly port: AvatarPort, private readonly policies: PolicyByTier {} async switchTo manifest: AvatarManifest, tier: DeviceTier : Promise<SwitchResult { const op = ++this.operation; const policy = this.policies tier ; const visibleId = this.current?.assetId ?? null; const policyFailure = this.validateManifest manifest, policy ; if policyFailure { this.failIfCurrent op, manifest.id, policyFailure ; return { ok: false, reason: policyFailure }; } this.state = { tag: "preparing", candidateId: manifest.id, stillShowing: visibleId }; let candidate: PreparedAvatar; try { candidate = await this.port.prepare manifest ; } catch error { const reason = Preparation failed: ${messageOf error } ; this.failIfCurrent op, manifest.id, reason ; return { ok: false, reason }; } if this.isCurrent op { await this.safeDispose candidate ; return { ok: false, reason: "Superseded by a newer selection", superseded: true }; } this.state = { tag: "qualifying", candidateId: manifest.id, stillShowing: visibleId }; let badFrames = 0; for let index = 0; index < policy.qualificationFrames; index++ { let sample: FrameProbe; try { sample = await this.port.probe candidate ; } catch error { await this.safeDispose candidate ; const reason = Qualification probe failed: ${messageOf error } ; this.failIfCurrent op, manifest.id, reason ; return { ok: false, reason }; } if this.isCurrent op { await this.safeDispose candidate ; return { ok: false, reason: "Superseded during qualification", superseded: true }; } const acceptable = sample.rendered && sample.tracking === "good" && sample.frameTimeMs <= policy.maxFrameTimeMs; if acceptable badFrames++; if badFrames policy.maxBadFrames { await this.safeDispose candidate ; const reason = "Candidate exceeded the qualification budget"; this.failIfCurrent op, manifest.id, reason ; return { ok: false, reason }; } } if this.isCurrent op { await this.safeDispose candidate ; return { ok: false, reason: "Superseded before commit", superseded: true }; } this.state = { tag: "committing", candidateId: manifest.id, stillShowing: visibleId }; const previous = this.current; try { this.port.activate candidate ; this.current = candidate; this.state = { tag: "showing", avatarId: candidate.assetId }; } catch error { try { this.port.restore previous ; } catch restoreError { const reason = Activation failed ${messageOf error } ; + restore also failed ${messageOf restoreError } ; await this.safeDispose candidate ; this.failIfCurrent op, manifest.id, reason ; return { ok: false, reason }; } await this.safeDispose candidate ; const reason = Activation failed: ${messageOf error } ; this.failIfCurrent op, manifest.id, reason ; return { ok: false, reason }; } if previous { try { await this.port.dispose previous ; } catch error { this.state = { tag: "showing", avatarId: candidate.assetId, warning: Old avatar cleanup failed: ${messageOf error } }; } } return { ok: true, avatarId: candidate.assetId }; } private validateManifest manifest: AvatarManifest, policy: TierPolicy : string | null { if policy.allow3dAvatar { return "3D avatars are disabled for this device tier"; } if manifest.id || manifest.revision { return "Manifest identity or revision is missing"; } if Number.isSafeInteger manifest.declaredBytes { return "Declared asset size is invalid"; } if manifest.declaredBytes <= 0 { return "Declared asset size must be positive"; } if manifest.declaredBytes policy.maxDeclaredBytes { return "Asset exceeds this tier's declared-size budget"; } return null; } private isCurrent op: number : boolean { return op === this.operation; } private failIfCurrent op: number, candidateId: string, reason: string : void { if this.isCurrent op return; this.state = { tag: "failed", candidateId, stillShowing: this.current?.assetId ?? null, reason }; } private async safeDispose candidate: PreparedAvatar : Promise<void { try { await this.port.dispose candidate ; } catch { // Record this through application telemetry in a real integration. } } } function messageOf error: unknown : string { return error instanceof Error ? error.message : String error ; } There are two details worth noticing. First, loading success does not imply presentation success. The candidate must produce enough acceptable probes before activation. Second, cleanup failure does not roll back a successful commit. At that point the new avatar is already the visible truth. Cleanup becomes a resource warning to observe and remediate, not a reason to lie to the UI about what is showing. Create src/avatar-loader.test.ts : js import { describe, expect, it } from "vitest"; import { AvatarLoader, AvatarManifest, AvatarPort, PreparedAvatar, examplePolicy } from "./avatar-loader"; class FakePort implements AvatarPort { active: PreparedAvatar | null = null; disposed: string = ; activationShouldFail = false; async prepare manifest: AvatarManifest : Promise<PreparedAvatar { return { assetId: manifest.id, revision: manifest.revision, opaqueHandle: {} }; } async probe { return { rendered: true, tracking: "good" as const, frameTimeMs: 20 }; } activate candidate: PreparedAvatar : void { if this.activationShouldFail { throw new Error "renderer rejected commit" ; } this.active = candidate; } restore previous: PreparedAvatar | null : void { this.active = previous; } async dispose candidate: PreparedAvatar : Promise<void { this.disposed.push candidate.assetId ; } } const asset = id: string : AvatarManifest = { id, revision: "1", format: "3d-avatar", declaredBytes: 1 000 000 } ; describe "AvatarLoader", = { it "commits a candidate only after qualification", async = { const port = new FakePort ; const loader = new AvatarLoader port, examplePolicy ; const result = await loader.switchTo asset "avatar-green" , "high" ; expect result .toEqual { ok: true, avatarId: "avatar-green" } ; expect port.active?.assetId .toBe "avatar-green" ; expect loader.state .toEqual { tag: "showing", avatarId: "avatar-green" } ; } ; it "restores the previous avatar when activation fails", async = { const port = new FakePort ; const loader = new AvatarLoader port, examplePolicy ; await loader.switchTo asset "known-good" , "high" ; port.activationShouldFail = true; const result = await loader.switchTo asset "candidate" , "high" ; expect result.ok .toBe false ; expect port.active?.assetId .toBe "known-good" ; expect loader.state .toMatchObject { tag: "failed", candidateId: "candidate", stillShowing: "known-good" } ; } ; it "does not attempt 3D activation on a disallowed tier", async = { const port = new FakePort ; const loader = new AvatarLoader port, examplePolicy ; const result = await loader.switchTo asset "heavy-avatar" , "low" ; expect result .toEqual { ok: false, reason: "3D avatars are disabled for this device tier" } ; expect port.active .toBeNull ; } ; } ; Run the suite: npm test These tests prove control-flow invariants. They do not prove that your real avatar renders correctly. That requires integration tests on target hardware. Keep the platform adapter narrow: class TencentBeautyAvatarAdapter implements AvatarPort { async prepare manifest: AvatarManifest : Promise<PreparedAvatar { // Load and initialize the avatar using the supported Beauty AR // integration for your selected platform. // Do not attach it to the visible output yet. throw new Error "Map to the documented platform integration" ; } async probe candidate: PreparedAvatar : Promise<FrameProbe { // Return observations collected by your application instrumentation. throw new Error "Implement application-level frame observations" ; } activate candidate: PreparedAvatar : void { // Atomically attach the prepared candidate to visible output. throw new Error "Implement documented activation behavior" ; } restore previous: PreparedAvatar | null : void { // Restore the previous avatar or the explicit avatar-paused view. throw new Error "Implement rollback behavior" ; } async dispose candidate: PreparedAvatar : Promise<void { // Release candidate-specific resources. throw new Error "Implement documented cleanup behavior" ; } } This skeleton is intentionally not filled with guessed API names. Use the SDK and platform instructions linked from the official Beauty AR documentation. The adapter contract gives that integration a testable meaning: If your integration cannot satisfy those rules, change the user experience accordingly. For example, introduce an explicit “avatar updating” scene rather than claiming that hot-swapping is atomic. Unit tests should be followed by controlled failure drills. Remove a required asset file or provide an invalid revision. Expected result: A manifest size check is not an integrity check. In production, validate the actual downloaded bytes and any integrity metadata supplied by your asset pipeline. Select avatars A, B, and C while A is still loading. Also test this with deliberately delayed downloads rather than relying on fast local assets. Cover the camera, move outside the supported pose, or otherwise reproduce the tracking-loss behavior relevant to your product. Do not use a single good frame as proof of readiness. Conversely, do not choose an arbitrary qualification window and call it universal. Measure how your application behaves across representative devices and user movement. Force the application into its low-device tier. Possible lower-cost experiences include a basic supported effect or no avatar effect. The exact ladder depends on the capabilities documented for your selected integration and on what the user has consented to show. Inject a failure into the adapter's activation boundary. restore previous runs. Let activation succeed, then make disposal of the previous asset fail. This distinguishes a presentation failure from a resource-lifecycle defect. A useful qualification policy combines several signals rather than hiding everything under “FPS looks okay.” | Signal | What it catches | Limitation | |---|---|---| | Candidate rendered | Missing or invalid output | Does not prove tracking quality | | Tracking state | Frozen or detached avatar behavior | Can vary with pose and environment | | Frame time | Expensive candidate rendering | Needs device-specific thresholds | | Asset revision | Stale or mismatched content | Does not validate runtime behavior | | Cleanup result | Resource lifecycle defects | Happens after the visible decision | For actual device-tier decisions, profile the full session workload: camera capture, Beauty AR processing, rendering, and RTC media behavior. A candidate that passes in an isolated asset viewer has not proved that it fits inside a live-call budget. AI can be genuinely useful for: It has not demonstrated production readiness merely by producing an asset that opens once. The durable engineering skill here is not hand-authoring every polygon. It is defining the boundaries the generated work must pass: identity, integrity, device policy, runtime qualification, commit semantics, rollback, and observable cleanup. That is also a healthier way to frame the anxiety around AI-assisted development. You do not have to compete with a generator at producing the first plausible artifact. Your responsibility is to decide what evidence makes that artifact trustworthy in a live system. Before enabling 3D avatar updates in a live Beauty AR session, verify that: The useful question for an avatar feature is not merely, “Can we generate it?” It is, “What must be true before we let it replace the presentation already working?” Relationship disclosure: I have a content relationship with Tencent RTC, and I used the official Tencent RTC Beauty AR documentation as the implementation reference for this article.