Reporting a player

phantom.aj.reportsOther players

Reporting players.

Scripts and plugins

A script has all of it, as phantom.aj.reports, and so does a plugin, from ctx.phantom(): the SDK runs in the plugin's own frame. Each call is marked with what it needs: game:read for what the area knows and hears, which "game": "read" in the manifest grants, and game:act for doing things in it as the player, which needs "game": "act" (see Permissions).

Overview

Member	What it does	Plugins
alreadyReported()	Whether a general report about this name already went out this sitting (FacilitatorXtCommManager._reportedPlayers), spelt as it was reported.	game:read
report()	Reports a player (sendReportAPlayerRequest, fr), or something specific they sent when about says what (sendReportWithAdditionalDataRequest, fra), and resolves once the server took it; REFUSED when it did not.	game:act
onSent()	Hears every report the client sends (fr, fra), whoever made it, as it goes out.	game:read
onVerdict()	Hears the server's verdict on every report, whoever made it: the popup's, or report's.	game:read

reports.window: The client's own report window: the card from a player's badge, and the how-to page.

Member	What it does	Plugins
current()	The report window, or null when none is open.	game:read
pressCard()	Presses one of the report card's buttons, as the player does.	game:act
reasons()	The reasons the card offers, in the player's language; none before the words are in.	game:read
setReason()	Writes one of the card's reasons into it, as picking it from its list does.	game:act
onChange()	Hears a report window open, with who it is about, and a reason being picked.	game:read

Methods

alreadyReported

methodplugins · game:read

alreadyReported(userName: string) => Promise<boolean>

Whether a general report about this name already went out this sitting (FacilitatorXtCommManager._reportedPlayers), spelt as it was reported. Content reports are not counted.

Parameters

Name	Type
userName	string

Returns

Promise<boolean>

report

methodplugins · game:act

report(userName: string, reason: "personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece", options?: ActOptions & { about?: ReportSubject | undefined; }) => Promise<Report>

Reports a player (sendReportAPlayerRequest, fr), or something specific they sent when about says what (sendReportWithAdditionalDataRequest, fra), and resolves once the server took it; REFUSED when it did not.

The client sends one general report per name a sitting (adventures aside): a second resolves at once with delivered: false, as the client answers it, and nothing is sent.

Parameters

Name	Type
userName	string
reason	"personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece"
options optional	ActOptions & { about?: ReportSubject | undefined; }

Returns

Promise<Report>

Types

ActOptions · Report · ReportSubject

Events

onSent

eventplugins · game:read

onSent(listener: (report: SentReport) => void) => () => void

Hears every report the client sends (fr, fra), whoever made it, as it goes out.

Parameters

Name	Type
listener	(report: SentReport) => void

Returns

() => void. Call it to stop listening.

Types

SentReport

onVerdict

eventplugins · game:read

onVerdict(listener: (verdict: ReportVerdict) => void) => () => void

Hears the server's verdict on every report, whoever made it: the popup's, or report's.

Parameters

Name	Type
listener	(verdict: ReportVerdict) => void

Returns

() => void. Call it to stop listening.

Types

ReportVerdict

reports.window

The client's own report window: the card from a player's badge, and the how-to page.

current

methodplugins · game:read

current() => Promise<ReportWindow | null>

The report window, or null when none is open.

Returns

Promise<ReportWindow \| null>

Types

ReportWindow

pressCard

methodplugins · game:act

pressCard(button: ReportCardButton, options?: ActOptions) => Promise<void>

Presses one of the report card's buttons, as the player does.

Parameters

Name	Type
button	ReportCardButton
options optional	ActOptions

Returns

Promise<void>

Types

ReportCardButton · ActOptions

reasons

methodplugins · game:read

reasons() => Promise<{ reason: "personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece"; words: string; }[]>

The reasons the card offers, in the player's language; none before the words are in.

Returns

Promise<{ reason: "personalInfo" \| "mean" \| "language" \| "security" \| "badDen" \| "scamming" \| "relationship" \| "username" \| "jamAGram" \| "wallPost" \| "masterpiece"; words: string; }[]>

setReason

methodplugins · game:act

setReason(reason: "personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece", options?: ActOptions) => Promise<string>

Writes one of the card's reasons into it, as picking it from its list does.

Parameters

Name	Type
reason	"personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece"
options optional	ActOptions

Returns

Promise<string>

Types

ActOptions

onChange

eventplugins · game:read

onChange(listener: (change: ReportChange) => void) => () => void

Hears a report window open, with who it is about, and a reason being picked.

Parameters

Name	Type
listener	(change: ReportChange) => void

Returns

() => void. Call it to stop listening.

Types

ReportChange

Types

The types the calls above take and give, with every field. Import any of them in a plugin from @phantomclient/plugin/sdk, or use them as they are in a script.

ActOptions

How long something that acts may take, and what may end it first.

Field	Type
timeoutMs optional	number | undefined	10 seconds by default.
signal optional	AbortSignal | undefined

Report

A report made, as report resolves with it.

Field	Type
userName	string
reason	"personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece"
reasonId	number
about	ReportSubject | null
delivered	boolean	Whether it went to the server. False only for a general report about someone the client already reported this sitting: the client answers that one itself and sends nothing.

ReportSubject

Something specific a report is about: a wall post's msgId, a jam-a-gram's id as text.

Field	Type
kind	"jamAGram" | "wallPost" | "masterpiece"
data	string

ReportVerdict

The server's verdict on a report: over a player (fr) or over something specific (fra).

Field	Type
over	"player" | "content"
taken	boolean

SentReport

A report the client sent, whoever made it, as onSent hears it.

Field	Type
userName	string
reason	"personalInfo" | "mean" | "language" | "security" | "badDen" | "scamming" | "relationship" | "username" | "jamAGram" | "wallPost" | "masterpiece" | null	The rule's name, or null for a number REPORT_REASONS does not name.
reasonId	number
dataType	number | null	For a report over something specific (fra): its dataType (7 or 8) and the thing.
data	string | null

ReportWindow

The report window: the card from a player's badge, or the how-to-report page.

Field	Type
kind	"card" | "howTo"
title	string | null
reason	string | null	The reason the card holds now.
picking	boolean	The reason list is open.

ReportCardButton

type ReportCardButton = 'report' | 'cancel' | 'reason' | 'close'

ReportChange

Something happening on the report window: it opened about someone, or a reason was picked.

type ReportChange = | {
      kind: 'opened';
      window: 'card' | 'howTo';
      userName: string | null;
      shownName: string | null;
      about: ReportAbout;
    }
  | { kind: 'reason'; reason: string }