troupe

func (Diagnostic) Location ¶

func (d Diagnostic) Location() string

Location gives where the diagnostic is in the conformance suite's form, without the file: "/scenarios/0/when" in a story, "header/players" in a session's header, and "message:3/changes/0" in a message. A message line without a valid ID is "line:<n>" instead, and a diagnostic from CheckChanges is its pointer within the message.

func (Keys) MarshalJSON ¶

func (k Keys) MarshalJSON() ([]byte, error)

MarshalJSON writes k as per is written: "cast", "*" or the list.

func (*Keys) UnmarshalJSON ¶

func (k *Keys) UnmarshalJSON(data []byte) error

UnmarshalJSON reads k as per is written.

func (*Package) Open ¶

func (p *Package) Open(path string) (io.ReadCloser, error)

Open opens the file of the package at path, such as one of Files, to read its content as a stream. It reads from the io.ReaderAt given to ReadPackage, which must stay unchanged, and is safe for concurrent use. Its error is an fs.ErrNotExist when path names no file of the package.

func (*Package) ReadSessions ¶

func (p *Package) ReadSessions() (map[string]*Session, []Diagnostic, error)

ReadSessions reads the package's sessions, by path, as a session reader does (Format 15.2). Its diagnostics are the package's at that level, ReadPackage's and the sessions', so they replace ReadPackage's. When any session is UNREADABLE or UNSUPPORTED_VERSION, the package fails whole: the sessions are nil, and the diagnostics only those (Format 15.3). The error is r's, when reading it fails.

func (Part) MarshalJSON ¶

func (p Part) MarshalJSON() ([]byte, error)

MarshalJSON writes p with the fields its type has: text for a text part, and src and alt for an image part.

func (*Play) Apply ¶

func (pl *Play) Apply(before State, m *Message) State

Apply returns the state after a message, given the state of this play before it: its parent's, or the initial state for a root. That is the state after the message's changes (Format 8.6), with what else depends on the path, such as the rounds so far, the player's character {{player}} means, the session entries in use, the rounds entries were recorded as activated in and who has been present (Format 6.1, 7.2, 9, 10.1, 11.3). Applying the messages of a path in turn gives the state at its last, so a caller that keeps each message's state never replays a path.

func (*Play) Cast ¶

func (pl *Play) Cast() []Member

Cast returns the play's cast, in cast order (Format 6.1, 11.2). In a session, that is the scenario cast with its seats filled by the players' header characters, then the new seats, then the joiners; a seat no player fills is left out. A scenario played on its own has no players, so it lists every member as written, seats included, with the default of one seat and every story character: what a person starting a session can choose from. Its seats aren't in the cast its states have (conformance README section 2).

func (*Play) CheckChanges ¶

func (pl *Play) CheckChanges(before State, changes []Change) []Diagnostic

CheckChanges judges the changes of a message not yet recorded, given before, the state at its parent. Each state key is judged as Check judges a recorded change's (Format 8.5), and against its variable's by, maxStep and oneWay, which Format 8.1 leaves to whoever records a change: the scene has no by, and an opening's change is held to none of them. Each change is judged against the state the ones before it leave. oneWay compares a state key's value there with the one the change gives it. maxStep bounds the sum of the moves of the message's changes by "model", either way, each from the state key's value before the change to the one it gives it, and is reported at the last that sets the state key validly. Values are compared normalized, an absent key of a "*" map counting as the default (Format 8.3, 8.6).

It returns a Diagnostic for each rule a state key breaks, sorted as Check's are, with Line 0 and the state key's Pointer within the message, such as "/changes/0/set/state.bell". Changes it accepts get none from Check once recorded as given; a caller that drops a refused change judges the rest again. Each change's by and set are as the schema requires, and only a root's first change is by "opening" (Format 11.1).

func (*Play) Initial ¶

func (pl *Play) Initial() State

Initial returns the state before any message (Format 8.6).

func (*Play) KnownBy ¶

func (pl *Play) KnownBy(before State, m *Message) [][]string

KnownBy returns who knows each part of message m (Format 7.4, 11.5): the IDs of the characters who know it, and "narrator" when the narrator does, in code point order. before is this play's state before m: its parent's, or the initial state for a root.

A part is known by its speaker, by the characters present after m's changes and, unless m is a root, by those present before them: the witness rule. A part's knownBy replaces the rule with exactly the listed characters. The narrator knows a part unless its knownBy leaves the narrator out, and knows every part in narrator mode. Nobody knows a hidden message's parts (Format 11.4).

func (*Play) Mode ¶

func (pl *Play) Mode() string

Mode returns the scenario's mode: "characters" or "narrator" (Format 6.2).

func (*Play) NarratorName ¶

func (pl *Play) NarratorName() string

NarratorName returns what text calls the narrator: the scenario's narratorName, or "the narrator" (Format 6).

func (*Play) PointAt ¶

func (pl *Play) PointAt(before State, recent []Message, char string) *Point

PointAt returns the evaluation point at the last of recent, for a message written for char, or for the narrator when char is "". recent are the last messages of the path to the point, oldest first, and before is this play's state before the first of them: the initial state when it is a root. recent needs only as many messages as the deepest scan reaches: at most 100 that aren't hidden and have content (Format 7.2). With no messages, the point is before any message, at before.

Building a point does the work every condition at it shares, so a caller evaluating many conditions builds it once.

func (*Play) Render ¶

func (pl *Play) Render(text string, c RenderContext, r *rand.Rand) string

Render returns author text with its macros resolved (Format 9): the texts of a story, and of a session's characters, worlds and entries, where macros resolve. A message part's text is RenderParts's to show, since a player's or model's words are used as written. r chooses each pick's option, so rendering is reproducible from the caller's source.

Text between {{ and }} that is no macro, or that names an undeclared variable, is left as written; a declared variable with nothing to show renders as nothing.

func (*Play) RenderParts ¶

func (pl *Play) RenderParts(before State, m *Message, r *rand.Rand) []Part

RenderParts returns m's parts as they are shown (Format 9), given this play's state before m, as KnownBy and Apply take it. In a root made from an opening, their text and alt resolve at the root, with each part's speaker as {{char}} and own meaning state; r chooses a pick's option, though a root has its picks chosen already (Format 11.1). Any other message is a player's or a model's words, used as written, so no state leaks through model output or prompt attacks (Format Appendix C).

func (*Play) Root ¶

func (pl *Play) Root(opening string, r *rand.Rand) (Message, error)

Root returns the root a session starts with when it plays the scenario's opening with the ID opening (Format 11.1): a system message naming the opening. Its content is the opening's as written, with each pick replaced by the option r chooses, escaped, or empty when the opening has none. When the opening has a set, the root records it as its first change, by "opening", without the state keys of each cast member marked player that players doesn't list, its character's variables and its key of "cast" variables, and with the players' characters added to the scene.present it sets. When no state key is left, it records no change. The caller gives the root its ID, and its at.

It fails when the scenario has no such opening.

func (*Play) StateAt ¶

func (pl *Play) StateAt(id string) (State, error)

StateAt returns the state at the session's message with the ID id, after its changes: those of every message on the path from its root, in order (Format 8.6).

func (*Play) StateKeys ¶

func (pl *Play) StateKeys() []StateKey

StateKeys returns the state keys the play's changes and its openings' set can write (Format 6.3, 8.5): scene.location and scene.present, then each variable in use, the scenario's, its worlds' and its characters', with a keyed variable's keys in their order, as State.All yields them. In a scenario played on its own, a "cast" variable's keys also include the characters of seats marked player, which its openings may set though its states leave them out (Format 8.5); a root leaves them out of a session where no player fills the seat (Format 11.1).

It offers what is valid, and Check still judges what is written: for a draft that fails Check, it gives the state keys of what reads, each once.

package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/TroupesAI/troupe-go"
)

func main() {
	st, _, err := troupe.ReadStory(strings.NewReader(`{"troupe": "0.15", "kind": "story",
		"characters": [{"id": "kai", "name": "Kai", "description": "A thief.",
			"variables": [{"id": "nerve", "type": "int", "min": 0, "max": 5, "description": "How steady Kai is."}]}],
		"scenarios": [{"id": "heist", "cast": [{}, {"character": "kai"}],
			"variables": [
				{"id": "bell", "type": "int", "description": "The last bell rung."},
				{"id": "trust", "type": "int", "per": "cast", "description": "Trust in the player."},
				{"id": "loot", "type": "int", "per": "*", "description": "What the crew carries."}]}]}`))
	if err != nil {
		log.Fatal(err)
	}
	play, err := troupe.NewScenarioPlay(st, "heist")
	if err != nil {
		log.Fatal(err)
	}
	for _, k := range play.StateKeys() {
		switch {
		case k.Variable == nil:
			fmt.Println(k.Name)
		case k.Key == "*":
			fmt.Println(k.Name+".<any ID>", k.Variable.Type, k.Owner)
		default:
			fmt.Println(k.Name, k.Variable.Type, k.Owner)
		}
	}
}

Output:
scene.location
scene.present
state.bell int heist
state.trust.kai int heist
state.loot.<any ID> int heist
state.kai.nerve int kai

func (*Play) UnmarshalState ¶

func (pl *Play) UnmarshalState(data []byte) (State, error)

UnmarshalState returns the state that State.MarshalJSON wrote as data. It is this play's state as it was stored, but for what the play has added since: a state key the stored state doesn't hold, such as one of a joiner the session's header has added, holds its initial value (Format 8.3).

It fails when data isn't a stored state, or holds a state key or value that isn't valid in this play (Format 8.5), and wraps ErrStateFormat when the state is stored in a format this release doesn't read.

func (*Play) Worlds ¶

func (pl *Play) Worlds() []*World

Worlds returns the worlds in use, in order: the scenario's worlds, or every story world when its worlds is absent, then the session's (Format 6.4).

func (*Point) Active ¶

func (p *Point) Active(retrieved []string, r *rand.Rand) []ActiveEntry

Active returns the entries active for the message being written at p (Format 7.2), in the order of their owners, the scenario, its worlds, the characters of the cast and the session, and each owner's in its order. The entries in use are the scenario's, its worlds', those of the characters present or the message is written for, and the session's; of these, those whoever the message is for knows (Format 7.4).

An entry with keywords activates when one matches its scanned text, a retrievable one when retrieved names its reference, one with both by either, and one with neither always, while its when holds. retrieved are the references of the entries the caller retrieved, of those Retrievable gives; any other reference changes nothing. The rounds of the messages that record an entry in activated time it: sticky keeps it active, and once and cooldown keep it from activating again. Of the entries that would activate, group keeps one of each owner's group, of the highest priority, chosen by weight among equals, where an entry sticky keeps wins against equals that aren't kept, and then chance lets each through, so a chosen entry that fails it leaves its group empty. r draws for weight and chance, so activation is reproducible from the caller's source.

Which active entries reach the model is the caller's to choose, by their priority, and where each goes by its position or depth (Format 7.3). The message being written records those that reach it in activated, apart from those Kept; one whose text renders as nothing or only whitespace reaches nothing (Format 11.4).

package main

import (
	"bytes"
	"encoding/json/v2"
	"fmt"
	"log"
	"math/rand/v2"
	"strings"

	"github.com/TroupesAI/troupe-go"
)

func main() {
	st, _, err := troupe.ReadStory(strings.NewReader(`{"troupe": "0.15", "kind": "story",
		"characters": [{"id": "kai", "name": "Kai", "description": "A thief.",
			"entries": [{"id": "fear", "text": "Kai fears heights.", "keywords": ["/roofs?/"], "sticky": 2}]}],
		"scenarios": [{"id": "heist", "cast": [{}, {"character": "kai"}],
			"openings": [{"id": "rooftop", "set": {"scene.present": ["kai"]},
				"content": [{"text": "Rain on the {{pick::roof::slates}}."}]}]}]}`))
	if err != nil {
		log.Fatal(err)
	}
	// The player's character, as a person typed it: its description is
	// escaped, since macros resolve there.
	header, err := json.Marshal(troupe.SessionHeader{
		Troupe:   troupe.Version,
		Scenario: "heist",
		Characters: []troupe.Character{{
			ID: "mara", Name: "Mara", Description: troupe.Escape("A smuggler {{who never pays}}."),
		}},
		Players: []string{"mara"},
	})
	if err != nil {
		log.Fatal(err)
	}
	s, _, err := troupe.ReadSession(bytes.NewReader(header))
	if err != nil {
		log.Fatal(err)
	}
	play, err := troupe.NewPlay(st, s)
	if err != nil {
		log.Fatal(err)
	}
	r := rand.New(rand.NewPCG(1, 2)) //nolint:gosec // G404: a seeded source makes the example reproducible

	root, err := play.Root("rooftop", r)
	if err != nil {
		log.Fatal(err)
	}
	root.ID = "1"
	fmt.Println(root.Content[0].Text, string(root.Changes[0].Set["scene.present"]))
	stored, err := json.Marshal(play.Apply(play.Initial(), &root))
	if err != nil {
		log.Fatal(err)
	}

	// Message 2 is written for Kai, after the root, which the scan reaches.
	reply := troupe.Message{ID: "2", Parent: "1", From: "model", Char: "kai", Content: []troupe.Part{{Text: "Kai grips the ledge."}}}
	for _, a := range play.PointAt(play.Initial(), []troupe.Message{root}, "kai").Active(nil, r) {
		fmt.Println(a.Owner+"/"+a.Entry.ID, a.Kept)
		if !a.Kept {
			reply.Activated = append(reply.Activated, a.Owner+"/"+a.Entry.ID)
		}
	}

	// Message 3 is written for Kai too, after message 2, from the root's
	// stored state.
	before, err := play.UnmarshalState(stored)
	if err != nil {
		log.Fatal(err)
	}
	for _, a := range play.PointAt(before, []troupe.Message{reply}, "kai").Active(nil, r) {
		fmt.Println(a.Owner+"/"+a.Entry.ID, a.Kept)
	}
}

Output:
Rain on the roof. ["kai","mara"]
kai/fear false
kai/fear true

func (*Point) Eval ¶

func (p *Point) Eval(expr, self string, scanDepth int) (bool, error)

Eval evaluates the condition expr of an entry owned by self, a character, world or scenario ID, or "session" for a session entry, which scans scanDepth messages: the entry's, 4 when it has none (Format 7.2, 10). It returns an error only when expr is a CEL_ERROR; a runtime error makes the condition false.

func (*Point) Retrievable ¶

func (p *Point) Retrievable() []ActiveEntry

Retrievable returns the retrievable entries that retrieving would activate at p, in Active's order: those that activate when retrieved and not otherwise, and that can win their group, since no entry of it active without retrieval has a higher priority, or an equal one and is kept (Format 7.2). chance is drawn only once they are retrieved. The caller retrieves those that are relevant, by their title or text, and passes their references to Active.

func (*Point) State ¶

func (p *Point) State() State

State returns the state at the point.

func (SessionHeader) MarshalJSON ¶

func (h SessionHeader) MarshalJSON() ([]byte, error)

MarshalJSON writes h as a session's header line, its kind included, with the members of maps sorted, as Story.MarshalJSON does.

func (State) All ¶

func (s State) All() iter.Seq2[string, any]

All yields every state key the state holds with its value, as Get gives them: scene.location and scene.present, then each variable in use, the scenario's, its worlds' and its characters', with a keyed variable's keys in their order: the cast's, the list's, or for a "*" map, code point order (Format 8.3).

func (State) Get ¶

func (s State) Get(key string) (any, bool)

Get returns the value at key, a state key (Format 8.5): "scene.location", "scene.present", a variable's full name, or a keyed variable's full name and one of its keys, such as "state.trust.kai". The value is a bool, an int64, a string, or a []string for a set and for scene.present. It reports false when the state holds nothing at key, as for a key a "*" map doesn't have.

func (State) MarshalJSON ¶

func (s State) MarshalJSON() ([]byte, error)

MarshalJSON returns s as JSON that UnmarshalState reads back: every state key and value s holds, and what else it keeps that depends on the path, such as the rounds, the session entries in use, when entries were recorded as activated and who has been present. The JSON names this module's Troupe version; a later release reads it back or wraps ErrStateFormat. No string in it holds U+0000, so a database's JSON type that refuses it, such as PostgreSQL's jsonb, can hold it.

It fails for the zero State.

func (State) Spoilers ¶

func (s State) Spoilers() []string

Spoilers returns the characters of the cast members marked spoiler that are still spoilers for players at s, in cast order: those that no state at a message on its path, the root's included, has present (Format 6.1). The cast starts present, so only a root that leaves a member out of scene.present, such as through an opening's set, keeps it a spoiler.

func (*Story) CheckID ¶

func (st *Story) CheckID(list, id string) error

CheckID reports whether an object added to the list at the JSON Pointer list can take the ID id (Format 2.3). The list is "/characters", "/worlds", "/scenarios", a world's "/worlds/0/locations", or the entries, variables or openings of a character, world or scenario, such as "/scenarios/0/openings". The error wraps ErrBadPointer for a pointer that names no such list, ErrIDInvalid, or ErrIDTaken when an object the list's objects must be unique among has id.

func (*Story) FileFields ¶

func (st *Story) FileFields() iter.Seq[FileField]

FileFields yields the story's fields that hold a file: its cover, then its characters' avatars, its locations' images and the image parts of its openings. It decodes each data: URI as it yields it, so only one is in memory at a time. In a story that fails the schema, a value of none of the three forms is left out.

func (Story) MarshalJSON ¶

func (st Story) MarshalJSON() ([]byte, error)

MarshalJSON writes st as a story document, its kind included, with the members of maps such as an opening's set sorted, so the same story always gives the same bytes.

func (*Story) RenameID ¶

func (st *Story) RenameID(object, id string) (jsontext.Value, []string, error)

RenameID returns the JSON Patch (RFC 6902) that gives the object at the JSON Pointer object the ID id, and rewrites every reference to it in the story, unless another object shares its ID; for the ID the object has, an empty one. The object is a character, world or scenario, such as "/characters/0", a world's location, or an entry, variable or opening, such as "/worlds/1/locations/2" or "/scenarios/0/variables/3". The patch moves a member it renames to the end of its object.

The references are the cast members, scenario worlds, parents, knownBy and speakers that name it, the state keys of openings' set and the scene values they write, and the names macros and conditions read, each resolved as Format 9 and 10 resolve it in the scenarios that use it. A keyed variable's key that is a renamed character's ID, as it is written in per, initial, set, macros and conditions, is renamed with it, since it shows as the character's name and char looks it up (Format 9, 10.1). In conditions, a string literal is a reference when it is compared with char, player, self, scenario, opening, scene.location, scene.present, scene.within or players.

It also returns pointers, into the story as it is, to the texts, conditions and values it leaves as written, whole, since rewriting them could change what they mean:

• a string value that is a renamed character's or location's ID, which shows as its name (Format 9): an enum's or set's values or labels, an initial value, or a value an opening sets, and a string literal equal to it that a condition uses any other way;
• a name in text or a condition of a character or world that refers to the object in one scenario that uses it, and to something else in another;
• a string literal that refers to the object but is written with escapes or as a raw string, a name that does but is written between backticks, a condition that doesn't parse and has the ID as a word, and a key whose renamed form its object already has;
• a renamed character's key of a list or "*" variable, wherever it is written, when the story already has the new ID as a word, since it may be a key of the same variable, which the two would merge into.

When another object shares the object's ID, which is DUPLICATE_ID (Format 15.3), what a reference to the ID refers to is the author's to say, so the patch only gives the object the ID, and every reference that could refer to the object, were it alone to have the ID, is left as written, and returned.

The error wraps ErrBadPointer for a pointer that names no such object, and otherwise ErrIDInvalid or ErrIDTaken as CheckID's does. In a story that fails the schema, a value that reads as absent is left as written, and not returned. A session played with the story isn't changed, so its references to the old ID name nothing.

package main

import (
	"errors"
	"fmt"
	"log"
	"strings"

	"github.com/TroupesAI/troupe-go"
)

func main() {
	st, _, err := troupe.ReadStory(strings.NewReader(`{"troupe": "0.15", "kind": "story",
		"characters": [{"id": "kai_moreau", "name": "Kai Moreau", "description": "A thief."}],
		"scenarios": [{"id": "heist", "cast": [{}, {"character": "kai_moreau"}],
			"entries": [{"id": "watch", "text": "The guard is near.", "when": "'kai_moreau' in scene.present"}]}]}`))
	if err != nil {
		log.Fatal(err)
	}
	if err := st.CheckID("/characters", "kai_moreau"); errors.Is(err, troupe.ErrIDTaken) {
		fmt.Println("taken")
	}
	patch, left, err := st.RenameID("/characters/0", "kai")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(patch), left)
}

Output:
taken
[{"op":"add","path":"/characters/0/id","value":"kai"},{"op":"replace","path":"/scenarios/0/cast/1/character","value":"kai"},{"op":"replace","path":"/scenarios/0/entries/0/when","value":"'kai' in scene.present"}] []