Sensei

PlaySafe's Sensei feature allows you to integrate intelligent AI agents directly into your Unity game. These agents, called Senseis, can converse with your players via text or voice, providing assistance, guidance, or enriching the game world based on the knowledge you provide them.

Think of Senseis as customizable NPCs powered by AI, capable of understanding and responding to player interactions within the context you define.

Core Concepts

Understanding these concepts is key to using Sensei effectively:

Personas

A Persona acts as the foundational "brain" for one or more Senseis. It defines the core personality traits, conversational style, and base knowledge set.

• Personality: You configure the general demeanor (e.g., helpful, formal, witty).
• Knowledge Base: Fed through Documents (see below).

Documents

Documents are the primary way you provide knowledge to a Persona. Currently, these are text-based files containing the information you want the associated Senseis to draw upon when interacting with players.

• A single Persona can utilize multiple Documents, allowing for modular knowledge management.
• The content of these documents directly influences how a Sensei responds to player queries or statements.

Senseis

A Sensei is a specific instance of a Persona that players can interact with in your game. While inheriting the Persona's core traits and knowledge, you might configure specific variations or contexts for different Senseis if needed (future capability).

• Players interact directly with Senseis, not Personas.
• Interactions can happen via text input or voice input (converted to text).

Sensei Chats

A Sensei Chat represents a single conversational session between a player and a Sensei. Each chat session has a unique identifier and tracks the back-and-forth messages.

• The SDK provides methods to start, manage messages within, and end these chat sessions.

Sensei Polls

A Sensei Poll allows you to attach simple feedback mechanisms or surveys to a Sensei. You can define questions and potential answers via the PlaySafe dashboard.

• Players can respond to these polls via the SDK.
• This provides a way to gather structured feedback related to the Sensei's performance or specific topics.

Setup

Before using Sensei features, ensure you have:

1. Installed and configured the PlaySafeManager as outlined in the Quickstart Guide.
2. Configured at least one Persona, Document, and Sensei in the PlaySafe Dashboard.
3. Obtained the Sensei ID for the specific Sensei you want players to interact with from the dashboard.

Interacting with Senseis

The PlaySafeManager provides methods to manage Sensei interactions. You'll typically call these from your own game scripts (e.g., an NPC interaction script, a UI manager).

Sending a Text Message

Once a session is active (currentSessionId is known), players can send text messages to the Sensei.

Method:

public IEnumerator SendSenseiTextMessage(
    string sessionId,
    string message,
    Action<SenseiChatMessageResponse> onSuccess,
    Action<string> onError
)

• sessionId: The active chat session ID obtained from StartSenseiChatSession.
• message: The text message content from the player.
• onSuccess: Callback invoked upon successful message processing. Receives SenseiChatMessageResponse containing the Sensei's Response text and the original Transcript (which is the input message here).
• onError: Callback for errors.

Example Usage (Continuing from SenseiInteraction):

    // Call this method when the player submits text (e.g., from an input field)
    public void SendTextMessage(string playerInput)
    {
        if (string.IsNullOrEmpty(currentSessionId))
        {
            Debug.LogError("Cannot send message: No active session ID.");
            return;
        }
        if (string.IsNullOrWhiteSpace(playerInput))
        {
            Debug.LogWarning("Cannot send empty message.");
            return;
        }

        Debug.Log($"Sending text message: '{playerInput}' in session: {currentSessionId}");
        StartCoroutine(playSafeManager.SendSenseiTextMessage(
            currentSessionId,
            playerInput,
            OnMessageResponse,
            OnInteractionError
        ));
    }

    private void OnMessageResponse(SenseiChatMessageResponse response)
    {
        Debug.Log($"Sensei Response: {response.Response}");
        // Display the Sensei's response in your game UI
        // You might also want to display the player's input (response.Transcript)
    }

Speak to Sensei

Players can also interact with Senseis using their voice. You'll need to record an AudioClip first (using Unity's Microphone class or another audio input system) and then send it.

Method:

public IEnumerator SendSenseiAudioMessage(
    string sessionId,
    AudioClip audioClip,
    Action<SenseiChatMessageResponse> onSuccess,
    Action<string> onError
)

• sessionId: The active chat session ID.
• audioClip: The Unity AudioClip containing the player's recorded voice input.
• onSuccess: Callback invoked upon successful processing. Receives SenseiChatMessageResponse. The Transcript field will contain the text transcribed from the audio, and Response contains the Sensei's reply.
• onError: Callback for errors.

Example Usage (Requires audio recording setup):

    // Assume you have recorded audio into 'recordedClip'
    public void SendAudioMessage(AudioClip recordedClip)
    {
        if (string.IsNullOrEmpty(currentSessionId))
        {
            Debug.LogError("Cannot send audio: No active session ID.");
            return;
        }
        if (recordedClip == null)
        {
            Debug.LogError("Cannot send null AudioClip.");
            return;
        }

        Debug.Log($"Sending audio message in session: {currentSessionId}");
        StartCoroutine(playSafeManager.SendSenseiAudioMessage(
            currentSessionId,
            recordedClip,
            OnAudioMessageResponse, // Potentially reuse OnMessageResponse or use a specific one
            OnInteractionError
        ));
    }

    private void OnAudioMessageResponse(SenseiChatMessageResponse response)
    {
        Debug.Log($"Audio Transcript: {response.Transcript}");
        Debug.Log($"Sensei Response: {response.Response}");
        // Display transcript and response in UI
    }

Polls

Sensei polls allow you to gather feedback from in-game players in realtime.

Fetching and Submitting Polls

You can retrieve polls associated with a Sensei and allow players to submit responses.

Getting Sensei Polls

Fetch the list of available polls for a specific Sensei.

Method:

public IEnumerator GetSenseiPolls(
    string senseiId,
    Action<SenseiPollsResponse> onSuccess,
    Action<string> onError
)

• senseiId: The ID of the Sensei whose polls you want to retrieve.
• onSuccess: Callback invoked with SenseiPollsResponse, which contains a List<SenseiPoll>.
• onError: Callback for errors.

Example Usage:

using System.Collections.Generic;
// ... other using statements ...

public class SenseiPollManager : MonoBehaviour
{
    [SerializeField] private PlaySafeManager playSafeManager; // Assign
    [SerializeField] private string targetSenseiId = "your-sensei-id-from-dashboard"; // Replace!

    private List<SenseiPoll> availablePolls;

    public void FetchPolls()
    {
        Debug.Log($"Fetching polls for Sensei: {targetSenseiId}");
        StartCoroutine(playSafeManager.GetSenseiPolls(
            targetSenseiId,
            OnPollsReceived,
            OnInteractionError
        ));
    }

    // TODO: Implementation pending
    private void OnPollsReceived(SenseiPollsResponse response)
    {
        availablePolls = response.Polls;
        Debug.Log($"Received {availablePolls.Count} polls.");
        // Populate UI with poll questions and options
        // Each SenseiPoll object has Id, Question, Options (List<string>)
        foreach (var poll in availablePolls)
        {
            Debug.Log($" - Poll ID: {poll.Id}, Question: {poll.Question}");
            // You'd typically use this data to build UI elements
        }
    }

    private void OnInteractionError(string error)
    {
        Debug.LogError($"Sensei Poll Error: {error}");
    }

    // ... method for submitting response ...
}

Submitting a Poll Response

After displaying a poll and getting the player's choice, submit their response.

Method:

public IEnumerator SubmitSenseiPollResponse(
    string senseiId,
    string pollId,
    string response, // The selected option text
    string userId,
    Action onSuccess,
    Action<string> onError
)

• senseiId: The ID of the Sensei the poll belongs to.
• pollId: The ID of the specific poll being answered.
• response: The text of the option selected by the player.
• userId: The ID of the player submitting the response.
• onSuccess: Callback invoked on successful submission.
• onError: Callback for errors.

Example Usage (Continuing from SenseiPollManager):

    // Call this when a player selects an option for a specific poll
    public void SubmitPollResponse(string pollId, string selectedOption)
    {
        string currentPlayerId = "player123"; // Get from your player management

        Debug.Log($"Submitting response '{selectedOption}' for poll {pollId}, Sensei {targetSenseiId}, User {currentPlayerId}");
        StartCoroutine(playSafeManager.SubmitSenseiPollResponse(
            targetSenseiId,
            pollId,
            selectedOption,
            currentPlayerId,
            OnPollSubmitted,
            OnInteractionError
        ));
    }

    private void OnPollSubmitted()
    {
        Debug.Log("Poll response submitted successfully.");
        // Maybe hide the poll UI or show a thank you message
    }

This covers the primary interactions with the Sensei system using the PlaySafe Unity SDK. Remember to replace placeholder IDs (your-sensei-id-from-dashboard, player123) with actual values from your PlaySafe dashboard and game logic. Always handle potential errors gracefully using the onError callbacks.