View as Markdown · AI documentation index
Class: Chat
Defined in: chat.ts:274
A single conversation: its transcript, its delivery cursor, and everything the player has or has not seen in it.
Remarks
State lives in the messenger store entity, so it survives saves, loads, and remounts. Every method that changes state is an action: call them from event handlers, never while a passage or component renders.
See
defineChat - Factory for creating a chat
Constructors
Constructor
new Chat(
id,options):Chat
Defined in: chat.ts:301
Creates a chat. Prefer defineChat.
Parameters
id
string
Unique, persistent identifier
options
ChatOptions = {}
Peer or participants, title, avatar, callbacks
Returns
Chat
Properties
id
readonlyid:string
Defined in: chat.ts:276
Unique, persistent identifier.
kind
readonlykind:ChatKind
Defined in: chat.ts:279
Whether this is a one-to-one chat or a group.
maxEntries
readonlymaxEntries:number
Defined in: chat.ts:285
Upper bound on retained entries. Infinity when uncapped.
peerId
readonlypeerId:string|undefined
Defined in: chat.ts:282
The other participant of a direct chat.
Accessors
activeScript
Get Signature
get activeScript():
Script|null
Defined in: chat.ts:488
Script currently being played, or null.
Returns
Script | null
canReply
Get Signature
get canReply():
boolean
Defined in: chat.ts:424
Whether a reply is possible at all.
Remarks
false in a read-only chat. A writable chat with nothing to answer right
now still reports true - check Chat.pendingChoice for that.
Returns
boolean
entries
Get Signature
get entries():
TranscriptEntry[]
Defined in: chat.ts:378
Delivered entries, oldest first.
Returns
firstUnreadKey
Get Signature
get firstUnreadKey():
string|null
Defined in: chat.ts:388
Key of the oldest unseen entry, or null.
Returns
string | null
isGroup
Get Signature
get isGroup():
boolean
Defined in: chat.ts:398
Whether this chat has several members rather than one peer.
Returns
boolean
lastEntry
Get Signature
get lastEntry():
TranscriptEntry|null
Defined in: chat.ts:393
Newest entry, or null when the transcript is empty.
Returns
TranscriptEntry | null
nextDueAt
Get Signature
get nextDueAt():
number|null
Defined in: chat.ts:497
Game time delivery is blocked until, or null when nothing is waiting.
Returns
number | null
participantCount
Get Signature
get participantCount():
number
Defined in: chat.ts:408
How many members the group currently has.
Returns
number
participants
Get Signature
get participants():
string[]
Defined in: chat.ts:403
Current members, as contact ids.
Returns
string[]
pendingChoice
Get Signature
get pendingChoice():
PendingChoice|null
Defined in: chat.ts:504
The reply the player is expected to pick, or null.
Returns
PendingChoice | null
readOnly
Get Signature
get readOnly():
boolean
Defined in: chat.ts:413
Whether the player is structurally barred from replying.
Returns
boolean
resolvedAvatar
Get Signature
get resolvedAvatar():
string|undefined
Defined in: chat.ts:462
Chat picture, or undefined when the chat has none.
Remarks
Resolution order: an in-fiction change (where null means the picture was
removed), then the definition's avatar, then the peer's avatar.
Returns
string | undefined
resolvedTitle
Get Signature
get resolvedTitle():
string
Defined in: chat.ts:435
Title, resolved through the definition and the peer.
Remarks
Resolution order: an in-fiction rename, then the definition's title, then the peer's name, then the chat id.
Returns
string
typingContacts
Get Signature
get typingContacts():
string[]
Defined in: chat.ts:483
Contacts currently shown as typing.
Returns
string[]
unread
Get Signature
get unread():
number
Defined in: chat.ts:383
Number of entries the player has not seen.
Returns
number
vars
Get Signature
get vars():
ChatVars
Defined in: chat.ts:365
This chat's persisted state, materialized on first access.
Remarks
Use it from anything that writes. Read-only accessors go through Chat.readVars instead, so merely looking at a chat - which is what rendering does - never writes to the store.
Returns
Methods
addParticipant()
addParticipant(
contact):void
Defined in: chat.ts:759
Adds a member and records an in-fiction notice.
Parameters
contact
Who joined
string | Contact
Returns
void
advance()
advance(
count):void
Defined in: chat.ts:583
Delivers up to count messages from the active script.
Stops early at a choice, at a wait or typing beat whose time has not
come, and at the end of the script. Control beats do not count towards
count.
Parameters
count
number = 1
How many messages to deliver
Returns
void
Example
h.actions([{ content: 'Read on', action: () => chat.advance() }]);
choose()
choose(
index):void
Defined in: chat.ts:640
Logs the player's reply and continues.
Parameters
index
number
Which of Chat.pendingChoice's options was picked
Returns
void
Throws
Error if the chat is read-only, nothing is pending, or the index does not exist
Remarks
After the reply is logged, an option's next script is played and advanced,
an option's next function is called, and an option without next simply
continues the current script.
clear()
clear():
void
Defined in: chat.ts:856
Empties the transcript and resets every cursor.
Returns
void
Remarks
The cross-save seen record is untouched, because it describes what the player has read across all playthroughs.
deliverDue()
deliverDue():
void
Defined in: chat.ts:597
Delivers everything that has become due, and clears expired typing indicators.
Returns
void
Remarks
Idempotent: what is due is derived from the cursor and the clock, never from a live timer. Call it when the game gains focus, when the player opens the messenger, after moving the clock, or on an interval - a save loaded long after a message was scheduled simply delivers it now.
initialVars()
initialVars():
ChatVars
Defined in: chat.ts:339
The initial persisted state of this chat.
Returns
Remarks
Pure: it creates no state and touches no store, so a component may use it as a fallback while rendering a chat nothing has written to yet.
isSeenEver()
isSeenEver(
beatId):boolean
Defined in: chat.ts:537
Whether the player has ever seen a script beat, across every save.
Parameters
beatId
string
Returns
boolean
Remarks
Backs "skip already-read text" and gallery unlocks. Call
messenger.loadSeen() during bootstrap before relying on it.
markSeen()
markSeen():
void
Defined in: chat.ts:714
Marks every entry as seen.
Returns
void
Remarks
This is the player-facing notion of "seen", not the in-fiction read receipt. Beats that came from a script are also recorded in the cross-save seen store.
markSeenUpTo()
markSeenUpTo(
key):void
Defined in: chat.ts:727
Marks entries up to and including key as seen.
Parameters
key
string
Entry key to stop at
Returns
void
Remarks
Use this when the chat view knows how far the player actually scrolled. An unknown key marks nothing.
play()
play(
script):void
Defined in: chat.ts:551
Starts a script from its first beat.
Parameters
script
The script to play
Returns
void
Throws
Error if the script is not registered
Remarks
Sets up the cursor without delivering anything, so the game decides when the first message appears. Call Chat.advance next.
push()
push(
beat):TranscriptEntry
Defined in: chat.ts:624
Appends a message outside of any script.
Parameters
beat
A message, system, or custom beat built with m
Returns
The appended entry
Throws
Error if the beat is a control beat, or carries content that cannot be stored without a script behind it
Example
chat.push(m.from(anna).text(m.t('anna.reminder')));
chat.push(m.player.text('on my way'));
chat.push(m.from(anna).text('look', { forwardedFrom: boris }));
removeParticipant()
removeParticipant(
contact):void
Defined in: chat.ts:785
Removes a member and records an in-fiction notice.
Parameters
contact
Who left
string | Contact
Returns
void
rename()
rename(
title):void
Defined in: chat.ts:812
Renames the chat in-fiction.
Parameters
title
New title, or undefined to fall back to the definition
StaticText | undefined
Returns
void
setAvatar()
setAvatar(
src):void
Defined in: chat.ts:829
Changes the chat picture in-fiction.
Parameters
src
New picture, null to remove it, or undefined to fall back
to the definition
string | null | undefined
Returns
void
setReadOnly()
setReadOnly(
readOnly):void
Defined in: chat.ts:845
Opens or closes the chat for replies in-fiction.
Parameters
readOnly
boolean
Whether replies are barred
Returns
void
setTyping()
setTyping(
sender,ms):void
Defined in: chat.ts:747
Shows a typing indicator for ms of game time, without holding anything
back.
Parameters
sender
Who is typing
string | Contact
ms
number
How long the indicator lasts, in game time
Returns
void