Skip to main content

Partner SDK NAF API

GeniesPartnerSDKNAF is a second product in the same package. It sits between the Partner SDK modules and NAF, and it exists for the jobs that need both — rendering a user's avatar, dressing it, and talking to it.

import GeniesPartnerSDKNAF

When to use it. The convenience methods here make managing avatars — and the link between the Partner SDK and NAF — much easier to follow: you hand them a GeniesAvatarRef or a wearable straight from the Inventory module and they do the right thing. Reach past them to NAF directly when you want more direct control over loading, composition, or the render loop.

AreaWhat it gives you
Avatar conveniencesNAFView extensions that take Partner SDK types directly
ChatGeniesChat — a conversation with a smart avatar, performed on the avatar

Avatar conveniences​

Extensions on NAFView. They take the types the Inventory module returns, so there's no ID juggling in between.

APIPurpose
loadAvatar(_ ref:silhouette:lods:)Render the avatar as published, without the user's saved outfit. Smart avatars keep their behavior.
loadUserAvatar(_ ref:silhouette:lods:)Render it with the user's saved outfit applied.
equip(_ wearable:lods:)Put on a wearable. NAF replaces whatever it displaces. Takes a GeniesCatalogWearable or GeniesOwnedWearable.
unequip(_ wearable:)Take a wearable off; returns once the avatar has rebuilt without it.
saveOutfit(to ref:)Save what's currently worn as the user's outfit. Returns the updated GeniesAvatar.
let ref = selected.ref                       // from listOwnedAvatars()
try await view.loadUserAvatar(ref) // what they saved is what renders

try await view.equip(hat) // a GeniesOwnedWearable
try await view.saveOutfit(to: ref) // what's worn is what saves

silhouette shows the low-detail stand-in while the full avatar streams in; lods is the LOD progression, defaulting to [0].

note

saveOutfit saves wearables only — the body isn't saved yet, because NAF can't report its subspecies. It also skips the base body and locally loaded units, which would fail the save.

A ref carrying neither an avatar nor a smart avatar ID throws GeniesNAFAvatarError.unsupportedRef.


Chat​

GeniesChat​

A conversation with a smart avatar loaded in a NAFView. NAF streams the reply and performs it on the avatar; the SDK plays the voice.

It's an ObservableObject, so SwiftUI can drive a UI straight off it.

let chat = try GeniesChat(avatar: ref, view: view)
let turn = chat.send("Hey, what are you up to?")

for await text in turn.reply {
transcript += text.displayText
}

Create it after the smart avatar has loaded, and call detach() before loading another avatar into the view.

The initializer throws .avatarCannotChat for a ref with no smart avatar, and .notConfigured before GeniesSDK.configure or when the view has no animated avatar loaded.

Options​

GeniesChat(avatar: ref, view: view, options: .init(mode: .voice(lipSync: true)))
ModeBehavior
.text(delivery:)Text replies. Send by typing or push-to-talk.
.voice(delivery:lipSync:)Spoken replies. lipSync adds facial animation generated from the voice. Default.
.live(serverURL:)A live voice conversation — open microphone, and the avatar can start turns and be talked over. Always lip-synced. Requires connect().

delivery is .streaming (the reply arrives as it's generated) or .whole (slower to start, simpler on poor networks).

managesAudioSession defaults to true; turn it off when your app owns the shared audio session.

caution

.live readies the microphone on connect(), so iOS shows its recording indicator from that point — not from the first spoken word.

Sending​

APIPurpose
send(_ text:)Send a message. Returns a GeniesChatTurn.
send(_ suggestion:)Send a GeniesChatSuggestion.
greet(instruction:)Have the avatar open the conversation.
regenerate()Redo the last reply. nil when there's nothing to redo.
interrupt()Stop the current reply.

Push-to-talk​

APIPurpose
startListening()Begin recording the user.
stopListening(vocabularyHint:)Stop and send what was heard. Returns the turn.
cancelListening()Discard the recording.

A recording with no speech in it fails with .nothingHeard.

Live conversations​

APIPurpose
connect()Join the realtime room. Required for .live.
disconnect()Leave it.
setMicrophoneEnabled(_:)Mute or unmute.

isConnected and microphoneEnabled are published; both are false outside .live.

Sessions and history​

APIPurpose
sessionIDThe current session. Set a stored one to continue it, nil to start fresh.
newSession()Start a fresh conversation.
continueLatestSession()Resume the most recent one. Returns its ID.
sessions(limit:before:)The user's conversations with this avatar, newest first.
history(sessionID:limit:before:)Messages in one session, newest first — reverse them for a transcript.

Both return pages with an olderCursor, nil when you've reached the end. Pass it back as before:.

Suggestions​

suggestions() returns [GeniesChatSuggestion] — tappable follow-ups. Each has a kind (.roleplay, .conversation, .moderated), the prompt that gets sent, and a short displayText for the chip.

Observing​

MemberPurpose
state.idle, .listening, .thinking, or .speaking. Published.
onTurnEvery turn as it starts — including ones the avatar begins on its own in .live.
voiceClockWhere the current reply's voice is. Poll once per frame to sync your own animation.
detach()Release the chat from the view.

Reply text​

A turn's reply is an AsyncStream<GeniesChatText>, revealed as the avatar says it.

PropertyNotes
plainTextThe words, without performance tags or formatting.
displayTextReady to show — narration comes wrapped in *…*.
kind.dialogue (spoken), .narration (shown, not spoken), or .other.
start / durationWhere it sits in its utterance, in seconds.

A turn's result is .completed, .interrupted, or .failed(GeniesChatError).

Errors​

GeniesChatError carries a code, a message, the httpStatus (0 when the failure came from inside the stream), the service's serviceCode, and requestID / traceID for support.

CodeMeans
.notConfiguredThe SDK isn't configured, or has no chat host.
.unauthorizedThe session was rejected — restore or refresh it.
.sessionNotFoundThe session belongs to another user or character.
.avatarCannotChatThe avatar has no smart avatar.
.voiceUnavailableNo usable voice — use .text mode instead.
.microphoneUnavailablePermission denied, or recording couldn't start.
.nothingHeardThe recording had no speech in it.
.invalidRequest / .network / .serviceRequest, transport, and generation failures.