Plots

Plots tracks the stories in your game. You author story arcs and upload them. While the player plays, Plots reads the events you send, starts and advances arcs, and tells Director what the story needs. This page covers the arc library, the running arcs, the Plots verdict in a decision, and what Plots costs.

How Plots works

• An arc is a story: a list of beats, with forks between them. An arc you author is authored. An arc Director starts from the template catalogue or invents is emergent. The template catalogue holds 1,144 folk-tale story templates and is the same on the hosted and the local Director.
• Your events feed Plots through POST /v2/events. For each player an event names (its player_id, or each of its players), Plots decides whether the event belongs to a running arc, completes its current beat, or could start a new story.
• Your policy says what Plots may do: whether Director may start arcs, where they may come from, how many a player may have, and how much of each arc reaches a decision.
• A decision at a stream position gets the arcs that matter for the deciding character as direction, and the reply carries a verdict that says what Plots did.

Plots never changes your game. It reports and suggests. Your engine stays the final authority.

The arc library

The library holds the arcs you author. When plots.sources in the policy includes authored, Plots offers them as candidates for a new arc. An account has at most 500 arcs, and one arc document is at most 262,144 bytes (256 KB).

Upload an arc

curl -X PUT https://director.eposyne.com/v2/plots/library \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @arc.json

{"arc_id": "arc.missing-sister", "stored": true}

One arc goes in each request. The arc_id is the id of the Arc entity. Upload an arc whose id the library already holds, and it replaces the old one. Replacing is always allowed, also when the library is full. Director stores every arc as authored, whatever its source says.

{
  "source": "authored",
  "entities": [
    {"id": "arc.missing-sister", "entity_type": "Arc", "name": "Beatrice's missing sister",
     "data": {"description": "Beatrice's sister vanished near the docks."}},
    {"id": "beat.hear-plea", "entity_type": "Beat", "name": "Hear Beatrice's plea",
     "data": {"description": "Beatrice asks the player to look for her sister.",
              "complete_when": "The player agrees to help."}},
    {"id": "beat.search-docks", "entity_type": "Beat", "name": "Search the docks",
     "data": {"description": "The player searches the docks for clues.",
              "complete_when": "The player finds the sister's scarf."}},
    {"id": "char.beatrice", "entity_type": "Character", "name": "Beatrice",
     "data": {"game_id": "npc-beatrice", "group": "harbour"}}
  ],
  "relationships": [
    {"from_id": "beat.hear-plea", "to_id": "arc.missing-sister", "relationship_type": "children", "order": 1},
    {"from_id": "beat.search-docks", "to_id": "arc.missing-sister", "relationship_type": "children", "order": 2},
    {"from_id": "beat.hear-plea", "to_id": "beat.search-docks", "relationship_type": "beat_beat"},
    {"from_id": "beat.hear-plea", "to_id": "char.beatrice", "relationship_type": "cast"}
  ],
  "schema": {
    "Arc": [{"name": "description", "type": "text", "description": "What the arc is about"}],
    "Beat": [
      {"name": "description", "type": "text", "description": "What happens in the beat"},
      {"name": "complete_when", "type": "text", "description": "What completes the beat"}
    ],
    "Character": [{"name": "group", "type": "string", "description": "The character's group"}]
  },
  "roles": []
}

The arc format

An arc is a small graph, written in four lists:

• entities: exactly one Arc, its Beat and ConditionalNode children, and the other things they refer to, such as Character, Location, or Item, or any type of your own. Each entity has an id, an entity_type, a name, and optional data.
• relationships: the structure. children (a child to the Arc, in the order given by order), beat_beat (an earlier node to a later one, through a ConditionalNode at a fork), cast (a Beat to a Character, a fixed binding), props (a Beat to an Item), and a location edge named takes place at, set in, or located in (a Beat to a Location). Other kinds are carried unchanged.
• schema: for each entity type, the list of fields it has, each with a name, a type, and a description. Every key in data that is not reserved is a project field the schema describes.
• roles: open role slots that Plots fills at run time with an eligible character. Write {{SLOT}} in a beat's name or description to use the character's name. A slot can be used as a token when it has only letters, digits, and underscores.

Some data keys have a fixed meaning:

Fields Director reads by name, every one of them optional:

Plots fills in fields the schema lists that are empty (missing, null, blank, an empty list, or an empty object), with a model call. It never changes a field you wrote.

Forks and conditions

A ConditionalNode is a fork. Its data.branches is a list of branches. Each branch has a label, an order (tried in ascending order), a target_id, and a condition.

• A condition in the guard form, $variable operator value, is a game rule. The operator is one of == != >= <= > <. Several clauses joined by spaces mean AND, and text after # is ignored. Director evaluates it with no model against the variables of the player's latest decision that named a stream position. A guard that is false is never overridden, unless plots.may_override_guards is on.
• Any other text in condition is judged by a model. A blank or null condition leaves the choice to Plots, which asks a model.
• A branch with a null target_id leads nowhere and is ignored.

The strict rules

Director checks the whole arc before it stores anything. An arc that breaks a rule is refused with 422 and nothing is stored. The detail starts with arc bundle rejected: and lists every reason, separated by semicolons.

{"detail": "arc bundle rejected: the bundle has an unknown member 'colour'; the bundle needs exactly one Arc entity, found 0"}

• The arc is a JSON object with only the members source, entities, relationships, schema, and roles. Any other member is refused. source is authored or emergent.
• entities is a list with at least one entity and exactly one Arc.
• An entity has only id, entity_type, name, and data. id is 1 to 128 characters, entity_type and name are not empty, and data is an object. Entity ids are unique inside the arc.
• A ConditionalNode has data.branches. A branch has a label. A branch order is a number, and target_id and condition are a string or null. Other members of a branch are allowed and ignored.
• Every non-null target_id names a Beat or ConditionalNode of the same arc.
• A relationship has only from_id, to_id, relationship_type, field_name, and order, and the first three are required. Both ends name an entity of the arc.
• game_id is a non-empty string, requires_roles is a list of non-empty strings, and reference_id is a string.
• In schema, each entity type maps to a list of fields, and each field has a non-empty name. type and description are strings.
• A role has only slot, description, and entity_type, and slot is not empty.
• The document is at most 262,144 bytes, or the answer is 422 with "code": "arc_too_large".

Library limits

{"detail": "...; delete an arc first, or replace one of those it holds", "code": "library_full"}

Reading the library counts toward no limit. Library writes have a limit of their own and do not use the request limit of 60 per minute.

List and delete

curl https://director.eposyne.com/v2/plots/library \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

{"arcs": [{"arc_id": "arc.missing-sister", "name": "Beatrice's missing sister"}]}

The list is in the order the arcs were first stored.

curl -i -X DELETE https://director.eposyne.com/v2/plots/library/arc.missing-sister \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

A delete answers 204 with no body. An id the library does not hold answers 404 with a plain detail. A deleted arc is no longer a candidate for a new arc. Arcs already running keep the version they started with and run to the end, so a delete never changes a story the player is in. Upload the arc again to bring it back.

Running arcs

Read the arcs a timeline sees:

curl "https://director.eposyne.com/v2/plots/runtime/arcs?world_instance_id=save-1&timeline_id=main&player_id=player-1" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

{
  "world_instance_id": "save-1",
  "timeline_id": "main",
  "player_id": "player-1",
  "arcs": [
    {
      "instance_id": "inst-7f3a",
      "arc_id": "arc.missing-sister",
      "title": "Beatrice's missing sister",
      "player_id": "player-1",
      "source": "authored",
      "status": "active",
      "current_beat": {"id": "beat.search-docks", "title": "Search the docks"},
      "previous_beat": {"id": "beat.hear-plea", "title": "Hear Beatrice's plea"},
      "bindings": {
        "cast:Beatrice": {"id": "npc-beatrice", "name": "Beatrice", "fixed": true}
      },
      "started_seq": 3,
      "updated_seq": 9
    }
  ]
}

• world_instance_id and timeline_id are required, each 1 to 128 characters and given once. A missing or malformed one answers 400 with a plain detail. player_id is optional and filters to one player.
• The read shows the arcs as Plots has processed the events so far. A child timeline sees the arcs as they were at its branch point, plus its own changes.
• A world or timeline Director has never received events for answers 200 with an empty list.
• The read calls no model, costs nothing, and counts toward no limit.

The Plots verdict in a decision

Name a stream position on POST /v2/decide and the reply carries what Plots did for the player since their previous decision.

curl -X POST "https://director.eposyne.com/v2/decide?world=save-1&timeline=main&after_seq=44" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

The stream position

• Give world, timeline, and after_seq together, once each, or none. One or two of them is a 422.
• With a position, Director first makes sure that every event of the timeline up to after_seq is held and processed by Plots and Memory, including events an earlier delivery deferred. It waits up to 10 seconds. Past that it answers 409 with the acknowledgement and the range it misses (missing) and a detail. No model is called and nothing is charged. Send the missing events, then repeat the decision.
• The event at after_seq tells Director which player and which character the decision is about. When the player is the actor, the character is the event's target. Otherwise the character is the actor. Name the player as player_id on that event, or list the players in players. The decision reports one player's verdicts, see Whose verdicts.
• Without a position the decision behaves as it always did: no verdict, no direction from Plots.

Whose verdicts

A decision reports the verdicts of one player. With a stream position, add the query parameter player_id to name whose:

curl -X POST "https://director.eposyne.com/v2/decide?world=save-1&timeline=main&after_seq=60&player_id=player-2" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

• Without player_id, the player is the one the event at after_seq names: its player_id, else the first of its players. An event that names no player gives a decision without Plots verdicts.
• The parameter needs a stream position. player_id without world, timeline, and after_seq is a 422, and so is an empty or repeated player_id.
• Every player has their own verdicts, and a decision reports and clears only those of the player it names. After a fight of two players, the decision for the second player names player_id=player-2 and carries the second player's verdicts. The first player's wait for the decision that names the first player.
• The other players an event lists are never the character who decides.

The verdict

{
  "schema": "eposyne.director.decision-response/v2",
  "changes": [
    {"name": "hale_mood", "value": "pleading", "rationale": "Hale needs the player's silence about the dark lamp."}
  ],
  "plots": {
    "steering": "subtle",
    "verdicts": [
      {
        "kind": "started",
        "seq": 44,
        "arc_instance_id": "inst-3c9e",
        "arc_name": "The Lighthouse Debt",
        "to_beat": "The dark lamp",
        "reason": "The player saw the lighthouse lamp go dark and is asking the keeper why."
      }
    ]
  }
}

seq is a number. verdicts is always an array.

• steering is the plots.steering of your policy.
• Each entry of verdicts is one event Plots acted on, in stream order. seq is the sequence number of that event.
• With nothing to report the member is still there, with an empty list: "plots": {"steering": "subtle", "verdicts": []}.
• The plots member is absent when the decision names no stream position, when Plots is off for your account, and when Plots failed. The decision is then made without direction from Plots.
• A verdict is reported once, by the decision that answers. A decision that ends in an error leaves its verdicts for the next one. A verdict belongs to its timeline, so one from a future the player abandoned is not reported on the child timeline.

The arcs that matter for the deciding character also reach the decision as direction, filtered by plots.relevance. That text is for Director. It is never knowledge the character holds, and it is not part of the response.

What Plots costs

• Storing arcs, listing them, reading running arcs, and sending events cost nothing. They are capped, see the limits.
• Every Plots model call costs usage credits, exactly like a decision: fitting an event to an arc, the gate for a new arc, choosing an arc, picking a branch, and filling in a beat.
• Plots makes one fitting call for every player an event names: one for an event with a player_id, and one for each player in players, up to 16. See Events for several players. Starting an arc adds a gate, a choosing, and a fill-in call. Completing a beat can add a call for each fork that needs a judgement, and a fill-in call for the next beat.
• The decision itself, with a stream position, is billed as a decision. A larger plots.relevance puts more arc text in its prompt.
• Judgements use the model you bind with shared.judgement_model, else the decision's model inside a decision, else your account's default model.
• A judgement your credits cannot pay for is skipped, and the event counts as processed. The events response reports it in refused_judgements, see Events.

The counts and the settings that change them are on Policy. What credits cover is on Billing and limits.