API Reference

This reference covers the GDScript classes provided by the Neocortex Godot SDK. The API mirrors the Unity SDK, using Godot signals in place of UnityEvents.

NeocortexSmartAgent

NeocortexSmartAgent is the primary node for talking to a Neocortex character. Add it to your scene, set the character_id, and call its send methods.

Properties

Methods

text_to_text

Sends a text message to the Neocortex project and expects a text response.

• Parameters:
  • message: The text message to send.

agent.chat_response_received.connect(func(response):
    print("Message: ", response.message)
    print("Action: ", response.action)
    print("Emotion: ", response.emotion)
)
agent.text_to_text("Hello, Neocortex!")

text_to_audio

Sends a text message to the Neocortex project and expects an audio response.

• Parameters:
  • message: The text message to send.

agent.audio_response_received.connect(func(audio):
    audio_stream_player.stream = audio
    audio_stream_player.play()
)
agent.text_to_audio("Hello, Neocortex!")

audio_to_text

Sends recorded audio to the Neocortex project. The audio is transcribed first (emitting transcription_received), then the chat runs and a text response is emitted.

• Parameters:
  • audio: The AudioStreamWAV to send.

agent.transcription_received.connect(func(text):
    print("You: ", text)
)
agent.audio_to_text(recording)

audio_to_audio

Sends recorded audio to the Neocortex project and expects an audio response, the full voice-in / voice-out flow.

• Parameters:
  • audio: The AudioStreamWAV to send.

agent.audio_response_received.connect(func(audio):
    audio_stream_player.stream = audio
    audio_stream_player.play()
)
agent.audio_to_audio(recording)

get_chat_history

Fetches the last chat messages of the current session, emitted via chat_history_received.

• Parameters:
  • limit: The number of past messages to fetch (default 10).

Signals

ApiRequest

ApiRequest is the high-level API client used internally by the Smart Agent. Use it directly when you need the standalone endpoints or beats support.

request_beats

When true, chat requests ask the server to split the reply into ordered per-emotion beats. The NeocortexChatResponse then contains a beats array, each entry carrying its own text and emotion.

generate_audio

Generates speech for a piece of text, voiced in the given emotion.

• Parameters:
  • character_id: Your project (character) ID.
  • message: The text to voice.
  • emotion: Emotion name in uppercase (e.g. "HAPPY").
• Returns: AudioStreamMP3, or null on failure.

var audio := await api_request.generate_audio(character_id, "Well done!", "PLEASED")
if audio:
    audio_stream_player.stream = audio
    audio_stream_player.play()

get_account

Fetches your developer account info (tier, owner email, credits remaining, next refresh). Read-only.

• Returns: NeocortexApiAccount, or null on failure.

get_usage

Fetches team credit status plus optional per-player / per-character usage. Read-only, poll it to gate Smart NPC features before limits are reached mid-conversation.

• Parameters:
  • player_id (optional): Include usage stats for this player.
  • character_id (optional): Include usage stats for this character.
• Returns: NeocortexApiUsage, or null on failure.

var usage := await api_request.get_usage(OS.get_unique_id(), character_id)
if usage and usage.status == "EMPTY":
    disable_smart_npc_features()

NeocortexSessionManager

NeocortexSessionManager is a static class that manages per-character conversation session IDs. Sessions are persisted to user:// so they survive restarts and work in exported builds.

Methods

set_session_id

Stores or updates the session ID for a character.

• Parameters:
  • character_id: The unique identifier for the character.
  • session_id: The session ID to store.

get_session_id

Retrieves the stored session ID for a character. Returns an empty string if no session ID is found.

• Parameters:
  • character_id: The unique identifier for the character.

clean_session_id

Clears the stored session ID for a character, effectively starting a new conversation history.

• Parameters:
  • character_id: The unique identifier for the character.

# Start a fresh conversation for this character
NeocortexSessionManager.clean_session_id("char_123")

NeocortexEventLogger

NeocortexEventLogger is a short-term gameplay event buffer sent to the character on each chat request, giving it context about what recently happened in your game.

It holds at most 20 events with a maximum of 64 characters each. Events are selected priority-first (High → Low), newest-first within each priority, and sent in their original order.

Methods

push

Records a game event.

• Parameters:
  • priority: NeocortexEnums.EventPriority.LOW, MEDIUM, or HIGH.
  • content: A short description of the event (max 64 characters).

NeocortexEventLogger.push(NeocortexEnums.EventPriority.HIGH, "Player picked up the ancient sword")

clear

Clears all recorded events.