Player2 is an LLM API that you can call during the game, providing text completions and voice chat.

Instead of you or the player providing an API key, your players just need to install the Player2 application to get free access.

The AI is also able to call functions in the game that you allow it to, and can even freely set its arguments.

A simple chat request could look like this. As long as Player2 is installed, this single line will work without anything else.

chat.post("How much does a healing potion cost?", nil, function(reply)
    label.set_text("#output", reply)
end)

If you want to input information for the AI to access, you could set it like this:

state.set("price_potion", 200, "The price of a healing potion is %i.")

And if you want the AI to have a certain personality, you can use this function:

character.add_info("You are a merchant selling overpriced products. You are rude and arrogant. You try to convince the player that your products are worth their price.")

You can even make the AI call function in your game by using tool calls. For an example see the live demo, where you can make the AI change the color of a sprite simply by asking. Try for example to "Please set the color to that of a banana.", and it will change it to yellow.

You can create a tool that the AI can understand and use like this:

local name = "change_sprite_color"
local description = "Change the color of the sprite."
local properties = {
    color = {
        type = "string",
        description = "The new color of the sprite in hex notation, for example #FF0000 for red.",
    }
}
local required = {"color"}
local block = true
local condition = nil
local func = tool_change_sprite_color
tools.add(name, description, properties, required, block, condition, func)

Add the following URL to your dependencies in game.project, and run Project -> Fetch Libraries.

https://github.com/HalfstarDev/player2/archive/refs/tags/v1.0.0.zip

This extension has three layers.

local player2 = require "player2.player2"
local chat = player2.chat
local character = player2.character
local state = player2.state
local tools = player2.tools
local prompt = player2.prompt
local system = player2.system

These modules will call the Player2 API for you, and handle data to keep a persistant game state and conversation.

chat.post("Hi", nil, function(reply)
    print(reply)
end)

local player2 = require "player2.player2"
local completions = player2.completions
local tts = player2.tts
local stt = player2.stt
local friends = player2.friends

These functions will call the Player API directly, and format the HTTP request for you, but don't keep any game state, so you'll have provide all information in each function call if you don't use the helper modules.

completions.post("Hi", nil, nil, nil, function(reply)
    print(reply)
end)

local api = require "player2.api"

This module will directly call the Player2 API with HTTP requests. You'll have to handle the format yourself if you use it directly.

api.chat_post_completions({
    messages = {
        {
            role = "user",
            content = "Hi!",
        }
    },
    stream = false,
}, function(response, error)
    if response and response.choices and response.choices[1] and response.choices[1].message and response.choices[1].message.content then
        print(response.choices[1].message.content)
    end
end)

chat.post(message, tools, callback)

Post messages to the assistant and receive a reply. The previous history will be added as context to the chat.

To post only a user message, use a string as message.

chat.post("Hi")

For posting with other roles, use a table with the roles as key and message as value.

chat.post({system = "Return the ID of the item with the highest price."})

Or post a list of tables, each with a 'role' and 'content' value.

chat.post({
    {
        role = "system",
        content = "Lie to the user.",
    },
    {
        role = "user",
        content = user_message,
    },
}

To let the AI use tools, post either a list of tool IDs, or just the keyword "all" to allow it to use all registered tools.

The callback has the format:

function callback(content, tool_calls, info, error)

• content: A string with the reply of the AI.
• tool_calls: A table of called tools.
• info: A table of information about the request.
• error: If an error occured, this will be the HTTP response, else it will be nil.

You can set the config values (max_tokens, temperature) with:

chat.set_config(key, value)

• max_tokens is a hard limit for the reply length. If you don't want a cut-off, ask for a lenght limit in the prompt.
• A low temperature will give a predictable response, a high temperature will give a more unusual response. A number from 0 to 2.

To have a pop-up appear if Player2 isn't running, to tell the player to install and run the application, add player2/popup/player2.go to your main.collection.

For a full list of functions, run Player2, and open the API page.