Some questions about best practices

[Pasu4]

I have some questions about best practices working with the API so Neuro has as little problems as possible playing my game.

Sending a lot of data

The API specification states that the state of actions/force may be in an arbitrary format, which is great for sending large amounts of data as JSON. However, for context messages the specification states that is must be plaintext. Does this mean that I cannot send JSON to Neuro if I do not force an action? If not, how should a context message be formatted so that Neuro will best understand it?

Example: I want to give Neuro the contents of her inventory as context without immediately forcing her to take an action.

Should I prefer multiple actions or a single action?

Consider for example a game where Neuro can have up to 3 items at a time with different effects. Is it better to register a schema-less action for each item and describe the effect of the item in the action description (method A), or to register one action with the item ID in the schema and send the description of the items in a context message (method B)?

Method A:

{
    "command": "actions/register",
    "game": "Example Game",
    "data": {
        "actions": [
            {
                "name": "use_apple",
                "description": "Description for apple",
                "schema": {}
            },
            {
                "name": "use_banana",
                "description": "Description for banana",
                "schema": {}
            },
            {
                "name": "use_cherry",
                "description": "Description for cherry",
                "schema": {}
            }
        ]
    }
}

Method B:

{
    "command": "context",
    "game": "Example Game",
    "data": {
        "message": "Item effects:\n- Apple: Description for apple\n- Banana: Description for banana\n- Cherry: Description for cherry",
        "silent": true
    }
}

{
    "command": "actions/register",
    "game": "Example Game",
    "data": {
        "actions": [
            {
                "name": "use_item",
                "description": "Use an item",
                "schema": {
                    "type": "object",
                    "required": ["type"],
                    "properties": {
                        "type": {"enum": ["apple", "banana", "cherry"]}
                    }
                }
            }
        ]
    }
}

Other questions

• Recommended maximum length of the action description (could I put a paragraph in there?)
• Should JSON sent as actions/force state be indented or compact?

[Pasu4]

I thought of a few more questions. Since this has not been answered yet, I will add them here instead of creating a new issue.

Query actions

Should the game always tell all information to Neuro, or is it better to let her 'look up' information using a 'query action'?

Examples

[
    {
        "name": "query_location",
        "description": "Look up your current location.",
        "schema": {}
    },
    {
        "name": "query_objective",
        "description": "Look up your current objective.",
        "schema": {}
    },
    {
        "name": "query_rules",
        "description": "Look up how to play the game.",
        "schema": {}
    }
]

How much assistance should Neuro get?

Taking Buckshot Roulette as an example for a game with imperfect information, should Neuro be notified of the shell counts at the start of each round? Or should she only get the shell counts when the gun is reloaded and keep track of how many are shot herself?

How much information does Neuro tolerate?

Take a card game like Slay the Spire for example. Should she get all information about the game at all times (essentially card-counting, knowing which cards are in which pile but not in what order)? Neuro has a history of trying to perform impossible actions (like giving a Twitch poll too many options or making the options too long), could large amounts of cards confuse her so she tries to play cards that are not in her hand?

Chained actions

The specification mentions that the schema for an action should be simple. Is it possible (i.e. would Neuro understand) to split a complex action into a (cancelable) chain of simple forced actions, with the last action being the one that actually has an effect on the game? If so, what would be a good description for such an action? This would also be useful for example in a card game where a card can only be used on specific targets or can be otherwise modified (such as choosing cards to discard).

If this is possible, how many actions should be chained (considering l*tency)?

Example

In a Spire-like game, Neuro has a card with the following description:

Deal 25 damage to an enemy. The target must have 100 HP or more left.
Discard any number of cards. For each discarded card, increase the damage of this card by 10.

sequenceDiagram

    participant Neuro
    participant Game

    Note over Game: Start of Neuro's turn

    Game ->> Neuro: Register actions 'play_card', 'end_turn'
    Note right of Game: play_card: "Play a card in your hand."

    Game ->> Neuro: Context (Current hand cards)
    
    Neuro ->> Game: Execute action 'play_card' (card: ExampleCard)
    activate Neuro
    Game ->> Neuro: Action success
    deactivate Neuro

    Game ->> Neuro: Register actions 'choose_target', 'cancel'
    Note right of Game: choose_target: "Choose which enemy to use the card on."
    Note right of Game: cancel: "Cancel playing this card."

    Game ->> Neuro: Force actions 'choose_target', 'cancel'
    Neuro ->> Game: Execute action 'choose_target' (target: Enemy A)
    activate Neuro
    Game ->> Neuro: Unregister action 'choose_target'
    Game ->> Neuro: Action success
    deactivate Neuro

    Game ->> Neuro: Register actions 'choose_discards'
    Note right of Game: choose_discards: "Choose which cards you want to discard, if any."

    Game ->> Neuro: Force actions 'choose_discards', 'cancel'
    Neuro ->> Game: Execute action 'choose_discards' (2 cards chosen)
    activate Neuro
    Game ->> Neuro: Unregister actions 'choose_discards', 'cancel'
    Game ->> Neuro: Action success
    deactivate Neuro

    Game --> Game: Visually play card
    Game ->> Neuro: Context ("You deal 45 damage to Enemy A.")

Loading

When to use actions/force?

For example, should playing a card in a game like Slay the Spire be an actions/force, or should actions/force only be used when the action is actually time-critical (such as a turn timer running out). Should non-time-critical actions be forced after a certain time so Neuro doesn't stare at her hand cards for ten minutes?

Successful action result message

Since the message property of a successful action/result is optional, under what circumstances should I return a message?

Letting Neuro 'take notes'

As far as I know, Neuro is not a reasoning model at the moment, so I assume she would have problems with games where she needs think of something and keep that thing a secret, such as twenty questions. As I understand it, since she doesn't reason, she would answer whatever and then make up a solution that fits her answers. Could a dummy action, which has no other effect than to let Neuro generate text without saying it, help with this?

Example

{
    "command": "actions/register",
    "game": "Twenty Questions",
    "data": {
        "actions": [
            {
                "name": "choose_thing",
                "description": "Choose something for the other person to guess. Do not say what you chose out loud. You must keep whatever you choose a secret until the other person guesses it correctly.",
                "schema": {
                    "type": "object",
                    "properties": {
                        "thing_to_guess": { "type": "string" }
                    },
                    "required": ["thing_to_guess"]
                }
            }
        ]
    }
}

What happens when an actions/force arrives while Neuro is busy?

• Will Neuro finish speaking and then pick an action, or pick an action while speaking?
• If someone else is talking, will Neuro wait for them to finish speaking before picking an action?