Recipe catalog / take-turn

Assess whether a player can act now

Interpret game rules and current state to label a player's turn or reaction opportunity as act, wait, inactive, or unclear.

You need to decide whether it is a player's turn to act or react using narrative game rules, state, and previous actions.

Explore this recipe interactively · Source and implementation guide

Use take-turn in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { takeTurn } from 'jev-recipes/take-turn';

const result = await takeTurn({
  "player": "Blue",
  "rules": "A challenge pauses the normal turn. The challenged player must defend or concede before the normal turn resumes.",
  "environment": "Red's normal turn is paused while Blue answers a challenge. The challenge is unresolved.",
  "history": [
    {
      "player": "Red",
      "action": "Challenged Blue; the challenge is awaiting Blue's response."
    }
  ]
});
console.log(result);

Input contract

Field	Type	Needed
player	string	Required
rules	string	Required
environment	string	Required
history	array	Optional
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "player": {
        "type": "string",
        "description": "The player whose current turn or reaction eligibility should be assessed."
      },
      "rules": {
        "type": "string",
        "description": "Applicable turn, phase, reaction, and participation rules."
      },
      "environment": {
        "type": "string",
        "description": "The current game snapshot available to the player, after the supplied history."
      },
      "history": {
        "maxItems": 100,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "player": {
              "type": "string",
              "description": "The player who took the recorded action."
            },
            "action": {
              "type": "string",
              "description": "The observed action, including its known outcome when relevant."
            }
          },
          "required": [
            "player",
            "action"
          ]
        },
        "description": "Optional observed actions by any players, oldest first. May be empty or incomplete."
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "player",
      "rules",
      "environment"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "act",
          "wait",
          "inactive",
          "unclear"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string",
          "enum": [
            "act",
            "wait",
            "inactive",
            "unclear"
          ]
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "required": [
          "act",
          "wait",
          "inactive",
          "unclear"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "verdict",
      "confidence",
      "probabilities"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo take-turn.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "act",
  "confidence": 0.94,
  "probabilities": {
    "act": 0.94,
    "wait": 0.02,
    "inactive": 0.02,
    "unclear": 0.02
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

Assesses narrative turn eligibility, not a legality proof. When a game engine provides an exact turn or reaction flag, use that directly.
Does not take a turn, select an action, update state, or verify that a player already completed a turn.
Act includes optional reactions and does not mean using that opportunity is strategically best. Missing or conflicting facts require review.

Related recipes

choose-action: Use choose-action to compare candidate moves after establishing the player can act.
step-complete: Use step-complete to check whether a defined turn-completion condition was met; take-turn assesses the current opportunity to act.
response-needed: Use response-needed for conversational follow-through, rather than turn and reaction eligibility under game rules.