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.
| Area | What it gives you |
|---|---|
| Avatar conveniences | NAFView extensions that take Partner SDK types directly |
| Chat | GeniesChat — 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.
| API | Purpose |
|---|---|
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].
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)))
| Mode | Behavior |
|---|---|
.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.
.live readies the microphone on connect(), so iOS shows its recording indicator from that point — not from the first spoken word.
Sending
| API | Purpose |
|---|---|
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
| API | Purpose |
|---|---|
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
| API | Purpose |
|---|---|
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
| API | Purpose |
|---|---|
sessionID | The 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
| Member | Purpose |
|---|---|
state | .idle, .listening, .thinking, or .speaking. Published. |
onTurn | Every turn as it starts — including ones the avatar begins on its own in .live. |
voiceClock | Where 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.
| Property | Notes |
|---|---|
plainText | The words, without performance tags or formatting. |
displayText | Ready to show — narration comes wrapped in *…*. |
kind | .dialogue (spoken), .narration (shown, not spoken), or .other. |
start / duration | Where 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.
| Code | Means |
|---|---|
.notConfigured | The SDK isn't configured, or has no chat host. |
.unauthorized | The session was rejected — restore or refresh it. |
.sessionNotFound | The session belongs to another user or character. |
.avatarCannotChat | The avatar has no smart avatar. |
.voiceUnavailable | No usable voice — use .text mode instead. |
.microphoneUnavailable | Permission denied, or recording couldn't start. |
.nothingHeard | The recording had no speech in it. |
.invalidRequest / .network / .service | Request, transport, and generation failures. |