Skip to Content
defold-typescript libraries
elefant-ai

elefant-ai/player2-ai-npc-defold/ainpc

AI NPCs for Defold through the Player2 desktop app: chat completions, spawned NPCs to talk to, and a stream of their responses.

  • GitHub: elefant-ai/player2-ai-npc-defold — pinned to ecda39f
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/elefant-ai/player2-ai-npc-defold/archive/ecda39f58b3811442cb6945e329b127c891f9bdb.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as ainpc from "ainpc"

Functions

chat_completion(body: Body | string, on_reply: ReplyCallback, on_fail: FailCallback)

Requests a chat completion. A string is sent as one user message: the extension pastes it into {"messages":[{"content":"<text>","role":"user"}]} without escaping, so text holding a quote, a backslash or a newline makes invalid JSON. Pass a body with a messages list to send arbitrary text.

Parameters

  • body: Body | string — The request body, or the text of one user message.
  • on_reply: ReplyCallback — Called with the completion.
  • on_fail: FailCallback — Called when the request fails.

npc_spawn(2 overloads)

  1. (body: Body, on_reply: ReplyCallback, on_fail: FailCallback)

    Spawns an NPC.

    Parameters

    • body: Body — The NPC definition, such as the name, short_name, character_description, system_prompt and voice_id the upstream example sends.
    • on_reply: ReplyCallback — Called with the spawn reply.
    • on_fail: FailCallback — Called when the request fails.
  2. (game_id: string, body: Body | string, on_reply: ReplyCallback, on_fail: FailCallback)

    Spawns an NPC from a body given as a table or as JSON text.

    Parameters

    • game_id: string — Accepted but not sent: the request path keeps the literal {game_id} placeholder. This form is the only one that takes the body as JSON text.
    • body: Body | string — The NPC definition, or JSON text sent as it is.
    • on_reply: ReplyCallback — Called with the spawn reply.
    • on_fail: FailCallback — Called when the request fails.

npc_chat(2 overloads)

  1. (npc_id: string, body: Body, on_reply: ReplyCallback, on_fail: FailCallback)

    Sends a message to a spawned NPC.

    Parameters

    • npc_id: string — The NPC to talk to.
    • body: Body — The message, such as the sender_message, sender_name and game_state_info the upstream example sends.
    • on_reply: ReplyCallback — Called with the chat reply.
    • on_fail: FailCallback — Called when the request fails.
  2. (game_id: string, npc_id: string, body: Body | string, on_reply: ReplyCallback, on_fail: FailCallback)

    Sends a message to a spawned NPC, given as a body or as text.

    Parameters

    • game_id: string — Accepted but not sent: the request path keeps the literal {game_id} placeholder.
    • npc_id: string — The NPC to talk to.
    • body: Body | string — The message body, or text sent as { sender_message = text, sender_name = "" }.
    • on_reply: ReplyCallback — Called with the chat reply.
    • on_fail: FailCallback — Called when the request fails.

npc_kill(2 overloads)

Removes a spawned NPC.

  1. (npc_id: string, on_reply: ReplyCallback, on_fail: FailCallback)

    Parameters

    • npc_id: string — The NPC to remove.
    • on_reply: ReplyCallback — Called when the NPC is removed.
    • on_fail: FailCallback — Called when the request fails.
  2. (game_id: string, npc_id: string, on_reply: ReplyCallback, on_fail: FailCallback)

    Parameters

    • game_id: string — Accepted but not sent: the request path keeps the literal {game_id} placeholder.
    • npc_id: string — The NPC to remove.
    • on_reply: ReplyCallback — Called when the NPC is removed.
    • on_fail: FailCallback — Called when the request fails.

npc_responses(2 overloads): number

  1. (on_receive: ReplyCallback, on_finish: (self: unknown) => void, on_fail: FailCallback)

    Opens the stream of NPC responses. Without a game_id the request path keeps the literal {game_id} placeholder.

    Parameters

    • on_receive: ReplyCallback — Called with each chunk the stream delivers, decoded as JSON when it parses, otherwise as text.
    • on_finish: (self: unknown) => void — Called when the stream ends, after on_fail when it failed.
    • on_fail: FailCallback — Called when the stream fails.
  2. (game_id: string, on_receive: ReplyCallback, on_finish: (self: unknown) => void, on_fail: FailCallback)

    Opens the stream of NPC responses for a game.

    Parameters

    • game_id: string — The game whose responses to stream; it replaces {game_id} in the request path.
    • on_receive: ReplyCallback — Called with each chunk the stream delivers, decoded as JSON when it parses, otherwise as text.
    • on_finish: (self: unknown) => void — Called when the stream ends, after on_fail when it failed.
    • on_fail: FailCallback — Called when the stream fails.

Returns

stop_npc_responses(stream_id: number)

Stops a stream opened by {@link ainpc.npc_responses}. An id that names no open stream is ignored.

Parameters

  • stream_id: number — The id npc_responses returned.

Types

type Body = Record<string, JsonValue>

type JsonValue = string | number | boolean | readonly JsonValue[] | { readonly [key: string]: JsonValue; }

type ReplyCallback = (self: unknown, reply: Reply) => void

type Reply = Record<string | number, unknown> | string | number | boolean | undefined

type FailCallback = (self: unknown, body: string, status: number) => void

On this page