Adventures
phantom.aj.adventuresPlaying
Adventures: lobby, actors, combat, treasure, rewards, routes.
Scripts and plugins
A script has all of it, as phantom.aj.adventures, 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 |
|---|---|---|
clearRoomTransition() | Clears the flags the client sets while it moves between rooms (RoomXtCommManager._loadingNewRoom, AvatarManager.joiningNewRoom, QuestManager._questExitPending), which a room change that failed part way leaves set, blocking every later join. | game:act |
current() | The adventure the client has running, or null outside one (QuestManager.inQuestRoom). | game:read |
leave() | Leaves the adventure the way its own exit button does (QuestManager.commandExit, which sends quest.exit and sets the client's exit flag, so it tidies the adventure away as the room changes), and resolves once the player is in a room outside it. | game:act |
phase() | Where the run stands now: rewards while the reward screen is up in an adventure, playing in one, lobby while a lobby is on screen, and idle otherwise. | game:read |
restart() | Asks the server for the adventure again (sendQuestCloneQuest), which is how a run is played once more without going back to the list, and resolves with the fresh start (qs). | game:act |
room() | The room the player is in, as the client names it (SFClient._currRoom.name): an adventure's rooms are quest_0<defId>.room_<phase>, and a phase of an adventure is a room. | game:read |
status() | What the client says of the adventure it is in, in one read; false and 0 outside one. | game:read |
onClientStep() | Hears one of the client's own adventure steps as it takes it (CLIENT_STEPS names them): the screens it puts up, the art it fetches, the popups answered, the NPC bodies' states. | game:read |
onEnd() | Hears the player come out of an adventure into a room outside it, with why. | game:read |
onPhase() | Hears the run move from one phase to the next on one listener: a lobby joined, the adventure started, its reward screen offered, and the player out of it (ended, a moment, after which it stands idle again). | game:read |
onStart() | Hears each adventure start (qs, alone or bundled), with every actor it starts with. | game:read |
adventures.lobby: Finding an adventure and getting into it: phantom.aj.adventures.lobby.
| Member | What it does | Plugins |
|---|---|---|
canPlaySideScroll() | Whether the player has come far enough through the side scrolling adventures to play this one, as QuestManager.canGoInPlatformAdventure works it out: the first of them always, each later one once the one before it is done (a bit of stat 435). | game:read |
current() | The lobby the player waits in, or null: the public lobby's screen (QuestManager._adventureJoin) or the private one (_privateAdventureJoin), with who waits in it. | game:read |
definition() | An adventure's definition (QuestXtCommManager.getScriptDef), read from what the client holds: the players it takes, the level it needs, members only, hard mode. | game:read |
host() | Opens a private adventure for the player to host (sendQuestCreatePrivate), as the members' popup does; others join with joinPrivate, and start and kick are the host's. | game:act |
ids() | The ids of the adventures the adventure list offers (QuestManager.getAvailableScriptDefs). | game:act |
join() | Joins a public adventure, or opens one if none is waiting, as the list's Join button does (sendQuestCreateJoinPublic), and resolves with the lobby once the server lets the player in. | game:act |
joinBuddy() | Joins a buddy's adventure, as their buddy card does (sendQuestJoinBuddy). | game:act |
joinPrivate() | Joins the private adventure a player in the room hosts (sendQuestJoinPrivate). | game:act |
kick() | Removes a player from the private lobby the player hosts (sendQuestPrivateKick), resolving with who waits once the server sends the lobby's new list (qw). | game:act |
leave() | Leaves the lobby before the adventure starts, as its close button does: the private lobby through privateAdventureJoinClose(true), the public one through closeAdventurePopups. | game:act |
list() | Every adventure the list offers, with its definition, in the list's order. | game:read |
openList() | Opens the adventure list, the screen the portal in Jamaa Township opens (QuestManager.openAdventureSelectPopup), and resolves once it is drawn (_adventureSelectPopup). | game:act |
play() | Presses Play on the join window open, the player's own first, as the player does. | game:act |
start() | Starts the adventure the player waits in (sendQuestStartRequest) and resolves with it once the server starts it (qs). | game:act |
window() | The join window on screen as it draws it (gui.AdventureJoin, gui.PrivateAdventureJoin): title, places, the players drawn in them and whether Play can be pressed. | game:read |
onJoin() | Hears every answer to a join, host or private join, whoever asked. | game:read |
onLeft() | Hears the server confirm the player left the lobby (qjx). | game:read |
onWaiting() | Hears who waits in the lobby each time it changes (qw), by their ids in the room. | game:read |
adventures.actors: The adventure's actors: phantom.aj.adventures.actors.
| Member | What it does | Plugins |
|---|---|---|
all() | Every actor the room has drawn, in the client's order; none outside an adventure. | game:read |
biggest() | The biggest phantom in the room, the boss found the way a player tells it: highest level, then most health, then most experience, then the nearest. | game:read |
contents() | What is standing in the room, sorted by what it is; leftovers opened or taken are left out. | game:read |
danger() | What near the player can hurt them, the least slack first: how far each is from the line where it notices the player (QuestActor.onAttackRadius), and whether the player is clear of it. | game:act |
entry() | One actor's entry in the adventure's dictionary, drawn or not: a variable's value, a goal's count (gui_goal1a), the difficulty (diff_level). | game:read |
find() | The actors that answer a query, read in a few messages. | game:read |
first() | The first actor a query finds, or null. | game:read |
follow() | Follows one actor on the client's own frames: where it is, where to aim, how far the player is, which way it is going, and whether it is gone, told when any of it changes. | game:act |
get() | One drawn actor by its id, or null when the room has not drawn it. | game:read |
groups() | The room's actors by group (<group>__<n>), as the client groups them. | game:read |
inspect() | Everything the client has on one actor in one look: its row, fighting state, the client's own working, its NPC view, notice radii and room path, and its definition. | game:read |
motion() | Where an actor is and how it moves, in one read: the client's own speed (_seekVelocity) pointed at where it is walking to (_targetX, _targetY). | game:read |
npc() | A phantom's or NPC's definition by id (QuestManager._npcDefs), or null before the pack. | game:read |
pathToPlayer() | Whether an actor, or any of its group, has a path to the player in its range (QuestManager.getNearestActorPathInGroupToPlayerInRange). | game:read |
place() | The client's own QuestActor, typed and held by handle, for anything this area does not wrap: setVisible, setSwfState, setPath, setChatBalloonText, its _npc view. | game:act |
pointInside() | Whether a point falls inside one of an actor's volumes (testPointInActorVolumes). | game:act |
position() | Where an actor's display object stands, or null when the room has not drawn it. | game:read |
reach() | How close the player has to be to act on an actor, where to aim, and whether they are there now: the client's own circles (handleMouseDown, onRadiusTest, actorCollisionTest). | game:read |
seek() | Asks for an actor to seek something (questActorSeek, qas): 0 nothing, 1 its path, 2 the player, 3 a plant. | game:act |
spawn() | Places an actor in the room as its scene does (QuestManager.initQuestActor), built from the adventure's dictionary; one already there is built again. | game:act |
touching() | Whether the client counts an actor as touching the player this frame (QuestManager.actorCollisionTest). | game:read |
trigger() | Sets an actor off, as the client does when the player clicks or reaches it (QuestXtCommManager.questActorTriggered, qat). | game:act |
untrigger() | Tells the server the player left an actor's area (questActorUntriggered, qaut). | game:act |
volumes() | The adventure's volumes: the oasis that wants watering, the cactus that wants sitting on, the blockers and triggers, with each one's progress from the dictionary (progress). | game:read |
watch() | Watches every actor in the room and the player on the client's own frames, told only when something moved or the roster changed (rosterChanged, the cue to find again). | game:act |
whenVolumeDone() | Waits for a volume to finish: its progress in the dictionary reaching 100, waited for inside the game. | game:read |
onApproach() | Hears an actor the server moves cross into, or back out of, the ground where it notices the player (_actorDefaultInnerRadius plus one avatar). | game:read |
onChange() | Hears everything the server says of the actors, alone or bundled in qqm: spawned, moved, hit, died, restored, a state set, a movie state, a path, an icon, a seek, an item picked up or put down, items moved. | game:read |
onCommand() | Hears the script's other commands (qcmd): say, ask, game, take item, exit, notify. | game:read |
adventures.combat: The fight in an adventure: phantom.aj.adventures.combat.
| Member | What it does | Plugins |
|---|---|---|
attack() | Launches the player's weapon at a point, as a click does (QuestManager.playerLaunchWeapon): thrown with ranged, swung otherwise. | game:act |
clearInFlight() | Takes every thrown weapon out of the air the way a miss does (QuestProjectile.handleHit with nothing hit) and retires every swing, on this screen only (a miss is never reported). | game:act |
effects() | What the client draws over a player (QuestManager._questPlayersDict, which getQuestPlayerData fills); the player's own when left out. | game:read |
experience() | The player's adventure experience (questXp, questLevel, questXPPercentage), or null. | game:read |
heal() | Tells the server a healing weapon landed on a player (questPlayerHeal), as the client does for a healing projectile it threw. | game:act |
health() | A player's health percentage in the adventure as the client keeps it (AvatarInfo .questHealthPercentage); the player's own when left out. | game:read |
hitAt() | The actor a shot landing at a point would hit (QuestManager.projectileRadiusCheck), asked without shooting. | game:read |
inFlight() | Every thrown weapon in the air and every swing being played out, read in two collects. | game:read |
inStealth() | Whether the client counts the player as hidden from phantoms (isPlayerInStealthVolume). | game:read |
keepWeaponReady() | Keeps the weapon ready to go off at once, the game writing its timer back to 0 every frame, until the handle is called. | game:act |
livePlayers() | How many players the adventure counts as standing (livePlayerCount); 1 when it never says. | game:read |
meleeTargets() | The actors a melee swing at a point would hit (QuestManager.meleeRadiusCheck). | game:act |
near() | The phantoms near a point, nearest first, by the client's own targeting (QuestManager.getNearestActivePhantom): on screen, alive, in range, no higher than maxLevel. | game:read |
nearest() | The nearest phantom to a point by the client's own targeting, or null. | game:read |
nearestPlant() | The nearest plant the client would aim a plant weapon at (QuestManager.getNearestPlant). | game:read |
playerData() | The client's own QuestPlayerData for a player (QuestManager._questPlayersDict), held by handle, for drawing over them: its handleHit, handleHealing, levelUp, dropOrb, playStatusText, playItemEmoticonSound. | game:read |
report() | Tells the server something of the fight, as the client's own call for it would, and resolves once that message has gone out. | game:act |
requestRespawn() | Asks the server to bring the player back after a defeat, as the defeat popup's button does (sendQuestPlayerRequestRespawn), at at or the nearest respawn point. | game:act |
respawn() | Puts the player at the last checkpoint the adventure gave (QuestManager.respawnPlayer), the client's own half of coming back: nothing is sent and no health returns (requestRespawn asks the server). | game:act |
setDisguise() | Draws a player disguised as one of the adventure's NPCs, or as themselves with null (QuestManager.handleAvSwitch), on this screen only. | game:act |
stats() | The player's attack and defence range as handleStatsUpdate wrote it onto AvatarInfo. | game:read |
strike() | Swings at an actor the way a click on it does (QuestActor.handleMouseDown at its collision point), so the client's own reach decides. | game:act |
weapon() | The weapon the client would fight with (QuestManager.getPlayerActiveWeapon): the strongest worn item of that kind, or the client's own fallback. | game:read |
whenWeaponReady() | Waits in the game until the weapon will go off again (_playerWeaponTimerProjectile at 0, counted down by the game's own frames). | game:read |
onAttack() | Hears an actor swing at a player (qap). | game:read |
onDefeated() | Hears a player beaten (qpd); for the player, the defeat popup follows. | game:read |
onDisguise() | Hears a player disguised as an NPC, or the disguise taken off (qavsw). | game:read |
onHealth() | Hears a player's health change, or a player come back (quhp, qrspn). | game:read |
onLaunch() | Hears another player or an actor throw or swing a weapon (qp, qm). | game:read |
onLevelUp() | Hears a player reach a level (qulu). | game:read |
onPlayerLeft() | Hears a player leave the adventure (qplq). | game:read |
onPlayerRoom() | Hears another player go to another room of the adventure (qrc). | game:read |
onRespawnGranted() | Hears the server let the player come back (qprr). | game:read |
onSideScroll() | Hears another player move in a side scrolling adventure (qssau). | game:read |
onStats() | Hears the player's attack and defence range change (qusu). | game:read |
onXp() | Hears the player earn experience (quxp). | game:read |
onZap() | Hears a beam or a phantom zap a player (qbzap, qpzap). | game:read |
adventures.walk: Walking in an adventure: phantom.aj.adventures.walk.
| Member | What it does | Plugins |
|---|---|---|
canReach() | Whether the player can get to an actor or a point, asked of the room's grid before a step is taken, with the nearest place they can stand when they cannot. | game:read |
chase() | Chases an actor that moves until the player is close enough to act on it, aiming ahead of it, swinging with strike and keeping at it with untilDefeated. | game:act |
distances() | How far each actor is on foot, by the room's grid; null for no place or no way there. | game:read |
order() | Actors put in the order that covers them with the least walking, each leg measured from where the last ended; the ones there is no way to are named rather than sorted last. | game:read |
plan() | The whole way to an actor or a point: the route, how long it is, and what is in the way. | game:read |
stop() | Stops the walk under way and the player with it (RoomManagerWorld.forceStopMovement). | game:act |
to() | Walks the player to an actor, reading its place again before each hop so one that moves is followed. | game:act |
toPoint() | Walks the player to a point in the room, resolving once within within (40 by default). | game:act |
adventures.crystals: An adventure's crystals: the goals they count towards, and the crystals standing in the room: phantom.aj.adventures.crystals.
| Member | What it does | Plugins |
|---|---|---|
actors() | Every crystal the room holds now, with the colour each fills a goal for, read from the client's own actors since an adventure places its crystals itself and the server never names them. | game:read |
progress() | The crystals gathered and each goal's progress, read from the adventure's own dictionary (gui_goal<n>a needs, gui_goal<n> counts) and _playerOrbCountTotal, measured as QuestManager.handleOrbsUpdate measures them. | game:read |
onCount() | Hears every crystal count the server sends (qporbs), lower ones included. | game:read |
onProgress() | Hears the crystals go up: each qporbs with a higher count than the last this listener heard (the client keeps only a rising count), with the progress read afresh. | game:read |
adventures.treasure: Treasure and items: what can be taken, and taking it the way the client's own clicks do: phantom.aj.adventures.treasure.
| Member | What it does | Plugins |
|---|---|---|
answer() | Keeps or turns down the prize a chest offered (questActorTreasureTriggered), and shows the chest opened as the popup's buttons do. | game:act |
collect() | Takes what an actor holds the way the client takes its kind: a chest or dropped treasure through its prize popup (keep decides an item; gems and crystals are always kept), an item by picking it up, anything else by setting it off where it stands. | game:act |
collectables() | The chests not opened, dropped treasure not taken and items still lying in the room. | game:read |
drop() | Drops the item the player carries (sendQuestDropItem), where they stand or at at, and resolves where the server put it down. | game:act |
movedItems() | Asks where players moved the adventure's items (sendQuestMovedItemsRequest, qmi). | game:act |
open() | Opens a chest as clicking it does (QuestActor.handleClick): marks it opened, sends questActorTriggered, takes its click icon away, and resolves with the prize the server offers. | game:act |
pickUp() | Picks up an item (types 15 and 17) as clicking it does (questPickUpItem), and resolves with the server's answer: picked up, or askToDrop naming what the player already carries. | game:act |
useOn() | Carries the item the player holds to an actor and puts it down there, which is what pouring a watering can into an oasis is. | game:act |
onItemGiven() | Hears the server hand the player an item, which the client picks up at once (qgi). | game:read |
onOffer() | Hears each prize a chest offers (qatt), however it was opened. | game:read |
onPickUp() | Hears what came of every pick up and put down in the adventure, anyone's (qpup). | game:read |
onReward() | Hears each thing the player came away with, once, from every source: a chest's offer joined to its answer, dropped treasure kept or turned down, an item picked up, a reward screen gift, an award. | game:read |
adventures.rewards: An adventure's reward screens: what the server offers, what the client will let the player take, and taking it the whole way a player does: phantom.aj.adventures.rewards.
| Member | What it does | Plugins |
|---|---|---|
answerGift() | Answers the gift popup in front of the reward screen with Keep or Turn Down, as its buttons do (onKeepRewardsGift, onDiscardRewardsGift), confirmed by the pick going out. | game:act |
autoTake() | Empties every reward screen the adventure puts up, for as long as it runs: onScreen and takeScreen together. | game:act |
choose() | Tells the server which gift was taken (sendPickGiftResult) and nothing else, for a screen that has gone: the screen itself does not learn of it, so use press while it is up. | game:act |
claimable() | The gifts the player can take. | game:read |
closeGoals() | Takes the goals screen a reached goal puts up away, so the player can move again, as the client removes it. | game:act |
finish() | Says every gift is picked (sendPickGiftComplete) and takes the screen and any gift popup away as the client does, confirmed by the client's qpgiftdone going out and the screen gone. | game:act |
press() | Presses one of the screen's treasures the whole way a player does (onAdventureRewardsOptions), waits for the gift popup it opens, and answers it (onKeepRewardsGift, or onDiscardRewardsGift with discard, which only an item allows). | game:act |
screen() | The reward screen as the client has drawn it: whether it is up, whether a gift popup is in front of it, and each treasure with whether the client will accept a press on it. | game:read |
take() | Takes the treasure an adventure owes and closes its screen: up to chests gifts (every one claimable by default), the kinds in prefer first, larger values first among one kind; none turns them down. | game:act |
takeScreen() | Takes everything one reward screen will give up, oldest goal first, reading the screen again between presses (a pick redraws it, and a goal reached meanwhile unlocks another), and makes sure it is gone. | game:act |
onChoice() | Hears the player's own gift choice going out, whichever screen it answers. | game:read |
onComplete() | Hears an adventure complete: the first reward screen it offers, once per adventure this listener sees start (qs). | game:read |
onOffer() | Hears each reward screen the server offers, with its gifts numbered as choose takes them. | game:read |
onScreen() | Hears the reward screen come up, once the client has drawn it, with what it will let the player take. | game:read |
adventures.dialogue: An adventure's talking popup and what else stands in front of the room: phantom.aj.adventures.dialogue.
| Member | What it does | Plugins |
|---|---|---|
answer() | Answers the question the popup is asking (onCommandAskConfirm) and closes it, as its yes and no buttons do. | game:act |
answerQuestion() | Answers a question the adventure's script asked (QuestXtCommManager.questAskComplete), with the actor and state its ask command carried, and resolves once the answer has gone out. | game:act |
autoAccept() | Answers the adventure's dialogues as they come up, as a player does: Next until the lines run out, and yes to a question unless answer says otherwise. | game:act |
blocking() | What is in the way of the player, named, in the order it is worth dealing with; empty when nothing is. | game:read |
close() | Closes the talking popup with its own close button (onTalkingPopupClose), which undarkens and runs whatever the lines were waiting to do. | game:act |
current() | The talking popup on screen, or null when none is up. | game:read |
isDarkened() | Whether the client has darkened the screen behind something (DarkenManager.isDarkened), which stops the player walking (RoomManagerView.followCursorTest tests it). | game:read |
next() | Presses Next (onOkBtn): the next page of the lines, or the popup closing on the last. | game:act |
openPlayers() | Opens the adventure's list of the other players in it (onQuestPlayersBtn), as its HUD button does, and resolves once it is open. | game:act |
show() | Puts up the adventure's talking popup with words of your own (QuestManager.showTalkingDialog), a page a string, with the actor's talking head and title when actorId is given. | game:act |
onBlocking() | Hears what is in the way change, the first list included: read in the game every few frames and told only when a screen comes or goes. | game:read |
adventures.scene: What the adventure shows and plays: phantom.aj.adventures.scene.
| Member | What it does | Plugins |
|---|---|---|
audio() | What the client's sound tables hold now: what plays, and which packs have loaded. | game:read |
darken() | Puts the adventure's darkness over the room (QuestManager.createDarkness), or, fromScene, only where the room's own scene asks for it (createDarknessFromScene). | game:act |
fade() | Fades to black or back with the client's own fader (handleFade(false) to fade out, _faderState 4 to take the sheet down, as a film ending does). | game:act |
fallingPhantoms() | The phantoms the adventure is raining down now (QuestManager._fallingPhantoms). | game:read |
finishCutscene() | Tells the server the adventure's film is finished (sendPlaySwfComplete), which its script waits for. | game:act |
keepAwake() | Keeps the client's idle timer at 0 (QuestManager._gameIdleTimer), the game writing it every frame, so the adventure never warns the player for sitting still nor puts them out at five minutes. | game:act |
keepLit() | Keeps every room's darkness hidden (_darknessMask.visible held false, the new mask of each room included) until the handle is called. | game:act |
lighten() | Takes the darkness away (QuestManager.removeDarkness), confirmed gone. | game:act |
loop() | Starts a sound looping (QuestManager.playLoopingSound) until the handle is called, which stops it (stopLoopingSound). | game:act |
musicStream() | One of the adventure's music streams by the name playMusic takes. | game:read |
objective() | The objective line on the HUD as the player reads it (GuiHud.questObjectiveTxt); '' for none. | game:read |
playMusic() | Changes the adventure's music (QuestManager.playMusic), fading out what plays; '0' is silence. | game:act |
playSound() | Plays one of the adventure's own sounds by name (QuestManager.playSound). | game:act |
setActorTorch() | Lights or puts out an actor's torch (QuestManager.handleQuestTorch), as the adventure's own qtorch does. | game:act |
setTimeLeft() | Sets the clock the client counts down (_guiTimerLocal). | game:act |
shake() | Shakes the room (QuestManager.handleShake) for that long, confirmed by its shake clock. | game:act |
showObjective() | Puts an objective on the HUD by its localisation id (QuestManager.commandNotify), with the chime, as the script's notify does. | game:act |
stopShaking() | Stops the room shaking now and puts the background back (_shaketimer emptied, then stopShake). | game:act |
timeLeft() | Seconds left on an adventure clock the client counts itself (QuestManager._guiTimerLocal); null when none runs. | game:read |
torch() | Gives a player a torch in the darkness, or takes it away (QuestManager.addTorch, removeTorch, at the client's own scale and offset). | game:act |
torches() | Every light the client has cut in the darkness, in its own order; empty with no darkness. | game:read |
onEffect() | Hears everything the adventure does to the screen and the speakers: sounds and voice overs, music, sound packs, fades, shakes, films and their preloads, torches, and the page views it records for Animal Jam. | game:read |
onObjective() | Hears each objective the adventure's script sets (qcmd notify), translated, in the order they came. | game:read |
adventures.garden: Seeds and the plants they grow into, in the adventures that use them: phantom.aj.adventures.garden.
| Member | What it does | Plugins |
|---|---|---|
canPlant() | Whether a seed may be planted at a point (QuestManager.validatePlantSeedLocation): inside a planting volume and not too near another plant. | game:read |
feed() | Feeds a phantom to a plant (sendEatPhantom), as the plant's own touch does, and resolves once the server says the plant ate it (qpa). | game:act |
plant() | Plants a seed at a point (sendPlantSeed), as dragging one onto a valid spot does, and resolves with the plant once the server says it took root for this player. | game:act |
plants() | The plants in the room (actor type 21), as the client holds them. | game:read |
satchel() | The seed satchel as the client holds it; open false outside a seed adventure. | game:read |
seeds() | The seeds the player holds, with how many and the most they may carry, read from the client. | game:read |
onPlantAte() | Hears a plant eat a phantom (qpa). | game:read |
onPlanted() | Hears a seed take root, or be refused, for anybody in the adventure (qps). | game:read |
onRecoil() | Hears a plant recoil after eating (qepr). | game:read |
onSeeds() | Hears the player's count of a seed change (qseed); defId 0 empties every seed. | game:read |
adventures.routes: Recording what the player's client asks of an adventure's actors, and playing it back: phantom.aj.adventures.routes.
| Member | What it does | Plugins |
|---|---|---|
match() | The actor a recorded step would be played on now, or the named reason there is none: the room is wrong, the chest already opened, nothing of the kind left standing. | game:read |
play() | Plays a recorded route back: each step in order, on the actor standing where the recorded one stood, in the room it belongs to. | game:act |
record() | Records what the player's client asks of actors from now on, until stopped. | game:read |
onStep() | Hears each thing the player's client asks of an actor (qat, qpup, qatt), whether the player clicked or a script did, with where the player and the actor stood, read just after the message passed. | game:read |
Methods
clearRoomTransition
clearRoomTransition(options?: ActOptions) => Promise<void>Clears the flags the client sets while it moves between rooms (RoomXtCommManager._loadingNewRoom, AvatarManager.joiningNewRoom, QuestManager._questExitPending), which a room change that failed part way leaves set, blocking every later join. Not for use while a room change is really under way. Resolves once all three read false.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
current
current() => Promise<RunningAdventure | null>The adventure the client has running, or null outside one (QuestManager.inQuestRoom).
Returns
Promise<RunningAdventure \| null>
Types
leave
leave(options?: ActOptions) => Promise<AdventureEnd>Leaves the adventure the way its own exit button does (QuestManager.commandExit, which sends quest.exit and sets the client's exit flag, so it tidies the adventure away as the room changes), and resolves once the player is in a room outside it. NOT_READY outside an adventure.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureEnd>
Types
phase
phase() => Promise<AdventurePhase>Where the run stands now: rewards while the reward screen is up in an adventure, playing in one, lobby while a lobby is on screen, and idle otherwise.
Returns
Promise<AdventurePhase>
Types
restart
restart(options?: ActOptions) => Promise<AdventureStart>Asks the server for the adventure again (sendQuestCloneQuest), which is how a run is played once more without going back to the list, and resolves with the fresh start (qs). Nothing in this build of the client sends it, so a server that ignores it is a TIMEOUT.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureStart>
Types
room
room() => Promise<string | null>The room the player is in, as the client names it (SFClient._currRoom.name): an adventure's rooms are quest_0<defId>.room_<phase>, and a phase of an adventure is a room.
Returns
Promise<string \| null>
status
status() => Promise<AdventureStatus>What the client says of the adventure it is in, in one read; false and 0 outside one.
Returns
Promise<AdventureStatus>
Types
Events
onClientStep
onClientStep(step: "started" | "playerAttacked" | "actorDeath" | "actorHealthStatus" | "healthUpdate" | "swipe" | "projectile" | "beamZap" | "phantomZap" | "actorAttackReported" | "phantomZapReported" | "destructibleAttacked" | "actorSeekRequested" | "weaponThrown" | "weaponSwung" | "playerDead" | "respawnRequested" | "statsUpdate" | "levelUp" | "xpUpdate" | "award" | "gemsTallied" | "spawn" | "spawnPlaced" | "spawnPlacedAtRoot" | "actorRoster" | "actorStatus" | "sceneAssets" | "roomJoined" | "playerJoined" | "roomChange" | "playerLeft" | "playerLeftTextDone" | "exitRoom" | "exitPressed" | "exitByType" | "roomMissing" | "actorPath" | "volumeProgress" | "treasureTriggered" | "itemPickedUp" | "itemsMoved" | "actorRestored" | "crystalGoals" | "seedGiven" | "seedPlanted" | "plantAte" | "plantRecoiled" | "fallingPhantoms" | "fallingPhantomCrossing" | "frame" | "fadeIn" | "fadeEnded" | "shakeStarted" | "shakeStep" | "lightFinished" | "cutsceneAsked" | "cutscenePreloaded" | "cutscenePlayed" | "actorSwfState" | "mediaLibrary" | "voiceOverEnded" | "levelShape" | "dialogueResized" | "pageOpened" | "assetTaken" | "assetPooled" | "questEvent" | "keyDown" | "keyUp" | "mousePressed" | "giftOffered" | "rewardScreenDrawn" | "rewardScreenRefreshed" | "rewardPressed" | "rewardPressedNonMember" | "rewardKept" | "rewardDiscarded" | "giftClosed" | "defeatAnswered" | "dropAnswered" | "leaveAnswered" | "leaveLobbyAnswered" | "leaveLobbyAsked" | "scriptPopupAnswered" | "scriptPopupYes" | "scriptPopupNo" | "scriptPopupOk" | "rewardScreenPressed" | "idleWarningAnswered" | "playerSelected" | "joinScreenOpened" | "joinScreenClosed" | "listOpened" | "listClosed" | "listWindowsLoaded" | "listRowPressed" | "privateLobbyMoved" | "adventureListLoaded" | "platformerListLoaded" | "rewardScreenLoaded" | "goalRewardScreenLoaded" | "rewardIconLoaded" | "dialogueLoaded" | "dialogueHeadLoaded" | "timerLoaded" | "hotColdLoaded" | "goalLoaded" | "levelShapeLoaded" | "fallingPhantomLoaded" | "cutsceneLoaded" | "soundsLoaded" | "globalSoundsLoaded" | "reportWindowsLoaded" | "awardPictureShown" | "awardPictureRemoved" | "newPlayerSkipped" | "newPlayerEditorReady" | "newPlayerShopOpened" | "newPlayerShopClosed" | "minigameCommand" | "setStateCommand" | "npcState" | "npcTurned" | "npcAnimation" | "npcSwfState" | "npcHealthBar" | "npcHitText" | "npcReady" | "npcArtLoaded" | "npcSecondaryArtLoaded" | "npcReset" | "npcBuilt" | "npcDestroyed", listener: (call: AdventureClientCall) => void, options?: ClientStepOptions) => () => voidHears one of the client's own adventure steps as it takes it (CLIENT_STEPS names them): the screens it puts up, the art it fetches, the popups answered, the NPC bodies' states. frame runs two dozen times a second, so give it every.
Parameters
| Name | Type | |
|---|---|---|
step | "started" | "playerAttacked" | "actorDeath" | "actorHealthStatus" | "healthUpdate" | "swipe" | "projectile" | "beamZap" | "phantomZap" | "actorAttackReported" | "phantomZapReported" | "destructibleAttacked" | "actorSeekRequested" | "weaponThrown" | "weaponSwung" | "playerDead" | "respawnRequested" | "statsUpdate" | "levelUp" | "xpUpdate" | "award" | "gemsTallied" | "spawn" | "spawnPlaced" | "spawnPlacedAtRoot" | "actorRoster" | "actorStatus" | "sceneAssets" | "roomJoined" | "playerJoined" | "roomChange" | "playerLeft" | "playerLeftTextDone" | "exitRoom" | "exitPressed" | "exitByType" | "roomMissing" | "actorPath" | "volumeProgress" | "treasureTriggered" | "itemPickedUp" | "itemsMoved" | "actorRestored" | "crystalGoals" | "seedGiven" | "seedPlanted" | "plantAte" | "plantRecoiled" | "fallingPhantoms" | "fallingPhantomCrossing" | "frame" | "fadeIn" | "fadeEnded" | "shakeStarted" | "shakeStep" | "lightFinished" | "cutsceneAsked" | "cutscenePreloaded" | "cutscenePlayed" | "actorSwfState" | "mediaLibrary" | "voiceOverEnded" | "levelShape" | "dialogueResized" | "pageOpened" | "assetTaken" | "assetPooled" | "questEvent" | "keyDown" | "keyUp" | "mousePressed" | "giftOffered" | "rewardScreenDrawn" | "rewardScreenRefreshed" | "rewardPressed" | "rewardPressedNonMember" | "rewardKept" | "rewardDiscarded" | "giftClosed" | "defeatAnswered" | "dropAnswered" | "leaveAnswered" | "leaveLobbyAnswered" | "leaveLobbyAsked" | "scriptPopupAnswered" | "scriptPopupYes" | "scriptPopupNo" | "scriptPopupOk" | "rewardScreenPressed" | "idleWarningAnswered" | "playerSelected" | "joinScreenOpened" | "joinScreenClosed" | "listOpened" | "listClosed" | "listWindowsLoaded" | "listRowPressed" | "privateLobbyMoved" | "adventureListLoaded" | "platformerListLoaded" | "rewardScreenLoaded" | "goalRewardScreenLoaded" | "rewardIconLoaded" | "dialogueLoaded" | "dialogueHeadLoaded" | "timerLoaded" | "hotColdLoaded" | "goalLoaded" | "levelShapeLoaded" | "fallingPhantomLoaded" | "cutsceneLoaded" | "soundsLoaded" | "globalSoundsLoaded" | "reportWindowsLoaded" | "awardPictureShown" | "awardPictureRemoved" | "newPlayerSkipped" | "newPlayerEditorReady" | "newPlayerShopOpened" | "newPlayerShopClosed" | "minigameCommand" | "setStateCommand" | "npcState" | "npcTurned" | "npcAnimation" | "npcSwfState" | "npcHealthBar" | "npcHitText" | "npcReady" | "npcArtLoaded" | "npcSecondaryArtLoaded" | "npcReset" | "npcBuilt" | "npcDestroyed" | |
listener | (call: AdventureClientCall) => void | |
options optional | ClientStepOptions |
Returns
() => void. Call it to stop listening.
Types
AdventureClientCall · ClientStepOptions
Example
const stop = phantom.aj.adventures.onClientStep('spawn', (call) => console.log(call.argList));onEnd
onEnd(listener: (end: AdventureEnd) => void) => () => voidHears the player come out of an adventure into a room outside it, with why.
The reason exists only in the traffic (the script's exit command, the server sending the player out), so each listener keeps what it heard since the adventure started; the adventure itself is read from the client as the listener starts, and taken from each start after.
Parameters
| Name | Type | |
|---|---|---|
listener | (end: AdventureEnd) => void |
Returns
() => void. Call it to stop listening.
Types
onPhase
onPhase(listener: (change: AdventurePhaseChange) => void) => () => voidHears the run move from one phase to the next on one listener: a lobby joined, the adventure started, its reward screen offered, and the player out of it (ended, a moment, after which it stands idle again). Told only when the phase really changes.
Parameters
| Name | Type | |
|---|---|---|
listener | (change: AdventurePhaseChange) => void |
Returns
() => void. Call it to stop listening.
Types
onStart
onStart(listener: (start: AdventureStart) => void) => () => voidHears each adventure start (qs, alone or bundled), with every actor it starts with.
Parameters
| Name | Type | |
|---|---|---|
listener | (start: AdventureStart) => void |
Returns
() => void. Call it to stop listening.
Types
adventures.lobby
Finding an adventure and getting into it: phantom.aj.adventures.lobby.
The adventure list, each adventure's definition, and the lobby the player waits in before one starts, all read from the client; and the joins, hosting, starting and leaving its own buttons do, each through the client's own QuestXtCommManager call so its screens follow along, and each confirmed by the server's answer.
const lobby = phantom.aj.adventures.lobby;
const [first] = await lobby.list();
if (first) {
await lobby.join(first.defId, { difficulty: 0 });
await lobby.start();
}canPlaySideScroll
canPlaySideScroll(scriptDefId: number) => Promise<boolean>Whether the player has come far enough through the side scrolling adventures to play this one, as QuestManager.canGoInPlatformAdventure works it out: the first of them always, each later one once the one before it is done (a bit of stat 435). False until the client has the list, which it asks the server for when the player first opens one; this only reads, so it never asks.
Parameters
| Name | Type | |
|---|---|---|
scriptDefId | number |
Returns
Promise<boolean>
current
current() => Promise<AdventureLobby | null>The lobby the player waits in, or null: the public lobby's screen (QuestManager._adventureJoin) or the private one (_privateAdventureJoin), with who waits in it.
Returns
Promise<AdventureLobby \| null>
Types
definition
definition(scriptDefId: number) => Promise<AdventureDefinition | null>An adventure's definition (QuestXtCommManager.getScriptDef), read from what the client holds: the players it takes, the level it needs, members only, hard mode. Null for an id the client has no definition for.
Parameters
| Name | Type | |
|---|---|---|
scriptDefId | number |
Returns
Promise<AdventureDefinition \| null>
Types
host
host(scriptDefId: number, options?: AdventureJoinOptions) => Promise<AdventureLobbyJoin>Opens a private adventure for the player to host (sendQuestCreatePrivate), as the members' popup does; others join with joinPrivate, and start and kick are the host's.
Parameters
| Name | Type | |
|---|---|---|
scriptDefId | number | |
options optional | AdventureJoinOptions |
Returns
Promise<AdventureLobbyJoin>
Types
ids
ids(options?: ActOptions) => Promise<number[]>The ids of the adventures the adventure list offers (QuestManager.getAvailableScriptDefs). The first time in a sitting the client fetches the list from the server, and this waits for it (TIMEOUT when it does not come).
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<number[]>
Types
join
join(scriptDefId: number, options?: ActOptions & { difficulty?: number | undefined; } & { autoStart?: boolean | undefined; }) => Promise<AdventureLobbyJoin>Joins a public adventure, or opens one if none is waiting, as the list's Join button does (sendQuestCreateJoinPublic), and resolves with the lobby once the server lets the player in. autoStart starts it as soon as the lobby fills. Throws REFUSED with the server's code (FULL, NM, NL...) in the message and in cause.refusal; TIMEOUT when no answer comes, which is the client refusing to send at all (mid room change, or Utility.canQuest saying no).
Parameters
| Name | Type | |
|---|---|---|
scriptDefId | number | |
options optional | ActOptions & { difficulty?: number | undefined; } & { autoStart?: boolean | undefined; } |
Returns
Promise<AdventureLobbyJoin>
Types
joinBuddy
joinBuddy(buddyUserName: string, options?: ActOptions) => Promise<AdventureLobbyJoin>Joins a buddy's adventure, as their buddy card does (sendQuestJoinBuddy). The client has no handler of its own for this request, so it resolves with whichever join answer comes next.
Parameters
| Name | Type | |
|---|---|---|
buddyUserName | string | |
options optional | ActOptions |
Returns
Promise<AdventureLobbyJoin>
Types
joinPrivate
joinPrivate(hostUserName: string, options?: ActOptions) => Promise<AdventureLobbyJoin>Joins the private adventure a player in the room hosts (sendQuestJoinPrivate).
Parameters
| Name | Type | |
|---|---|---|
hostUserName | string | |
options optional | ActOptions |
Returns
Promise<AdventureLobbyJoin>
Types
kick
kick(userName: string, options?: ActOptions) => Promise<number[]>Removes a player from the private lobby the player hosts (sendQuestPrivateKick), resolving with who waits once the server sends the lobby's new list (qw).
Parameters
| Name | Type | |
|---|---|---|
userName | string | |
options optional | ActOptions |
Returns
Promise<number[]>
Types
leave
leave(options?: ActOptions) => Promise<void>Leaves the lobby before the adventure starts, as its close button does: the private lobby through privateAdventureJoinClose(true), the public one through closeAdventurePopups. Both send quest.join-cancel, which is what this waits for. Resolves at once when there is no lobby.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
list
list(options?: ActOptions) => Promise<AdventureDefinition[]>Every adventure the list offers, with its definition, in the list's order. Loads the list the first time, as ids does; an id the client has no definition for is left out.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureDefinition[]>
Types
openList
openList(options?: ActOptions) => Promise<void>Opens the adventure list, the screen the portal in Jamaa Township opens (QuestManager.openAdventureSelectPopup), and resolves once it is drawn (_adventureSelectPopup).
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
play
play(options?: ActOptions) => Promise<AdventureWindow>Presses Play on the join window open, the player's own first, as the player does.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureWindow>
Types
start
start(options?: ActOptions) => Promise<AdventureStart>Starts the adventure the player waits in (sendQuestStartRequest) and resolves with it once the server starts it (qs). The server decides who may start a lobby; one it will not start for this player is a TIMEOUT.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureStart>
Types
window
window() => Promise<AdventureWindow | null>The join window on screen as it draws it (gui.AdventureJoin, gui.PrivateAdventureJoin): title, places, the players drawn in them and whether Play can be pressed. The player's own first; null when neither is open.
Returns
Promise<AdventureWindow \| null>
Types
onJoin
onJoin(listener: (answer: AdventureJoinAnswer) => void) => () => voidHears every answer to a join, host or private join, whoever asked.
Parameters
| Name | Type | |
|---|---|---|
listener | (answer: AdventureJoinAnswer) => void |
Returns
() => void. Call it to stop listening.
Types
onLeft
onLeft(listener: () => void) => () => voidHears the server confirm the player left the lobby (qjx).
Parameters
| Name | Type | |
|---|---|---|
listener | () => void |
Returns
() => void. Call it to stop listening.
onWaiting
onWaiting(listener: (userIds: number[]) => void) => () => voidHears who waits in the lobby each time it changes (qw), by their ids in the room.
Parameters
| Name | Type | |
|---|---|---|
listener | (userIds: number[]) => void |
Returns
() => void. Call it to stop listening.
adventures.actors
The adventure's actors: phantom.aj.adventures.actors. Everything is read from the client's own QuestActors (QuestManager._questActors, _questActorsDict) and the adventure's dictionary, so it knows actors the server never names (the crystals an adventure places) and where placed actors stand. What the server says of them is onChange.
Anything one client member does to one actor is the actor's own: place(id) hands over its QuestActor, typed, to read, write and call.
const [boss] = await phantom.aj.adventures.actors.find({ kinds: ['attacker'], sort: 'level', descending: true, limit: 1 });
const chest = await phantom.aj.adventures.actors.place('chest_3');
await chest?.setChatBalloonText('Open me!', false, false);
await chest?.$release();all
all() => Promise<AdventureActor[]>Every actor the room has drawn, in the client's order; none outside an adventure.
Returns
Promise<AdventureActor[]>
Types
biggest
biggest(query?: Omit<ActorQuery, "sort" | "limit">) => Promise<FoundActor | null>The biggest phantom in the room, the boss found the way a player tells it: highest level, then most health, then most experience, then the nearest. Null when there is none.
Parameters
| Name | Type | |
|---|---|---|
query optional | Omit<ActorQuery, "sort" | "limit"> |
Returns
Promise<FoundActor \| null>
Types
contents
contents() => Promise<AdventureContents>What is standing in the room, sorted by what it is; leftovers opened or taken are left out.
Returns
Promise<AdventureContents>
Types
danger
danger(options?: DangerOptions) => Promise<AdventureDanger[]>What near the player can hurt them, the least slack first: how far each is from the line where it notices the player (QuestActor.onAttackRadius), and whether the player is clear of it.
Parameters
| Name | Type | |
|---|---|---|
options optional | DangerOptions |
Returns
Promise<AdventureDanger[]>
Types
entry
entry(actorId: string) => Promise<AdventureActorEntry | null>One actor's entry in the adventure's dictionary, drawn or not: a variable's value, a goal's count (gui_goal1a), the difficulty (diff_level). Null for an id the adventure lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<AdventureActorEntry \| null>
Types
find
find(query?: ActorQuery) => Promise<FoundActor[]>The actors that answer a query, read in a few messages. See ActorQuery.
Parameters
| Name | Type | |
|---|---|---|
query optional | ActorQuery |
Returns
Promise<FoundActor[]>
Types
first
first(query?: ActorQuery) => Promise<FoundActor | null>The first actor a query finds, or null.
Parameters
| Name | Type | |
|---|---|---|
query optional | ActorQuery |
Returns
Promise<FoundActor \| null>
Types
follow
follow(actorId: string, listener: (actor: ActorFollowed) => void, options?: FollowOptions) => Promise<ActorFollow>Follows one actor on the client's own frames: where it is, where to aim, how far the player is, which way it is going, and whether it is gone, told when any of it changes. NOT_READY for an actor the room lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
listener | (actor: ActorFollowed) => void | |
options optional | FollowOptions |
Returns
Promise<ActorFollow>
Types
get
get(actorId: string) => Promise<AdventureActor | null>One drawn actor by its id, or null when the room has not drawn it.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<AdventureActor \| null>
Types
groups
groups() => Promise<Record<string, string[]>>The room's actors by group (<group>__<n>), as the client groups them.
Returns
Promise<Record<string, string[]>>
inspect
inspect(actorId: string) => Promise<ActorDetail | null>Everything the client has on one actor in one look: its row, fighting state, the client's own working, its NPC view, notice radii and room path, and its definition. Null when not drawn.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<ActorDetail \| null>
Types
motion
motion(actorId: string) => Promise<Motion | null>Where an actor is and how it moves, in one read: the client's own speed (_seekVelocity) pointed at where it is walking to (_targetX, _targetY). Null for an actor the room lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<Motion \| null>
Types
npc
npc(defId: number) => Promise<AdventureNpcDefinition | null>A phantom's or NPC's definition by id (QuestManager._npcDefs), or null before the pack.
Parameters
| Name | Type | |
|---|---|---|
defId | number |
Returns
Promise<AdventureNpcDefinition \| null>
Types
pathToPlayer
pathToPlayer(actorId: string) => Promise<boolean>Whether an actor, or any of its group, has a path to the player in its range (QuestManager.getNearestActorPathInGroupToPlayerInRange). False for an actor the room lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<boolean>
place
place(actorId: string) => Promise<TypedFlash<QuestActor> | null>The client's own QuestActor, typed and held by handle, for anything this area does not wrap: setVisible, setSwfState, setPath, setChatBalloonText, its _npc view. Null when the room has none. Release it with $release when done.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<TypedFlash<QuestActor> \| null>
Types
TypedFlash · FlashRead · FlashWrite · HoldOptions · HookTest · FlashArgumentLike · FlashPlace · FlashValue · FlashArgument · FlashData · AnyFlash · FlashMethod · FlashConstructor
pointInside
pointInside(actorId: string, point: Point) => Promise<boolean>Whether a point falls inside one of an actor's volumes (testPointInActorVolumes).
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
point | Point |
Returns
Promise<boolean>
Types
position
position(actorId: string) => Promise<Point | null>Where an actor's display object stands, or null when the room has not drawn it.
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<Point \| null>
Types
reach
reach(actorId: string) => Promise<ActorReach | null>How close the player has to be to act on an actor, where to aim, and whether they are there now: the client's own circles (handleMouseDown, onRadiusTest, actorCollisionTest).
Parameters
| Name | Type | |
|---|---|---|
actorId | string |
Returns
Promise<ActorReach \| null>
Types
seek
seek(actorId: string, seekType: number, options?: ActOptions) => Promise<void>Asks for an actor to seek something (questActorSeek, qas): 0 nothing, 1 its path, 2 the player, 3 a plant. Resolves once the request went out; onChange hears the seek the server keeps. A local actor (_l_…) is answered by the client itself and sends nothing, so it times out.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
seekType | number | |
options optional | ActOptions |
Returns
Promise<void>
Types
spawn
spawn(actorId: string, options?: SpawnOptions) => Promise<AdventureActor>Places an actor in the room as its scene does (QuestManager.initQuestActor), built from the adventure's dictionary; one already there is built again. This screen only: Animal Jam never hears of it. Resolves once the room holds it.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | SpawnOptions |
Returns
Promise<AdventureActor>
Types
touching
touching(actorId: string, options?: { playerOnly?: boolean | undefined; }) => Promise<boolean>Whether the client counts an actor as touching the player this frame (QuestManager.actorCollisionTest). By default an actor jammed against another attacker drawn in front of it counts too; playerOnly asks about the player alone.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | { playerOnly?: boolean | undefined; } |
Returns
Promise<boolean>
trigger
trigger(actorId: string, options?: ActOptions & { value?: number | undefined; }) => Promise<void>Sets an actor off, as the client does when the player clicks or reaches it (QuestXtCommManager.questActorTriggered, qat). value is 0 for most actors; dropped treasure takes 1 to keep its prize. Resolves once the client's message has gone out; what the actor does is the server's.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ActOptions & { value?: number | undefined; } |
Returns
Promise<void>
Types
untrigger
untrigger(actorId: string, options?: ActOptions) => Promise<void>Tells the server the player left an actor's area (questActorUntriggered, qaut).
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ActOptions |
Returns
Promise<void>
Types
volumes
volumes(options?: { kinds?: readonly ("volumeBlocker" | "volumeFallingPhantom" | "volumeHealth" | "volumeInteraction" | "volumePlacement" | "volumeTrigger")[] | undefined; }) => Promise<AdventureVolume[]>The adventure's volumes: the oasis that wants watering, the cactus that wants sitting on, the blockers and triggers, with each one's progress from the dictionary (progress).
Parameters
| Name | Type | |
|---|---|---|
options optional | { kinds?: readonly ("volumeBlocker" | "volumeFallingPhantom" | "volumeHealth" | "volumeInteraction" | "volumePlacement" | "volumeTrigger")[] | undefined; } |
Returns
Promise<AdventureVolume[]>
Types
watch
watch(listener: (room: ActorsAt) => void, options?: FollowOptions) => Promise<Running>Watches every actor in the room and the player on the client's own frames, told only when something moved or the roster changed (rosterChanged, the cue to find again).
Parameters
| Name | Type | |
|---|---|---|
listener | (room: ActorsAt) => void | |
options optional | FollowOptions |
Returns
Promise<Running>
Types
ActorsAt · ActorAt · Running · FollowOptions
whenVolumeDone
whenVolumeDone(actorId: string, options?: ActOptions) => Promise<void>Waits for a volume to finish: its progress in the dictionary reaching 100, waited for inside the game. It does nothing to make that happen; sitting or pouring is the caller's. TIMEOUT (30 seconds by default) when it stops being ticked along.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ActOptions |
Returns
Promise<void>
Types
onApproach
onApproach(listener: (approach: ActorApproach) => void) => () => voidHears an actor the server moves cross into, or back out of, the ground where it notices the player (_actorDefaultInnerRadius plus one avatar).
Parameters
| Name | Type | |
|---|---|---|
listener | (approach: ActorApproach) => void |
Returns
() => void. Call it to stop listening.
Types
onChange
onChange(listener: (change: ActorChange) => void) => () => voidHears everything the server says of the actors, alone or bundled in qqm: spawned, moved, hit, died, restored, a state set, a movie state, a path, an icon, a seek, an item picked up or put down, items moved. One event, a kind on each.
Parameters
| Name | Type | |
|---|---|---|
listener | (change: ActorChange) => void |
Returns
() => void. Call it to stop listening.
Types
Example
const stop = phantom.aj.adventures.actors.onChange((change) => {
if (change.kind === 'spawned' && change.prize) console.log('dropped', change.prize.kind);
});onCommand
onCommand(listener: (command: ScriptCommand) => void) => () => voidHears the script's other commands (qcmd): say, ask, game, take item, exit, notify.
Parameters
| Name | Type | |
|---|---|---|
listener | (command: ScriptCommand) => void |
Returns
() => void. Call it to stop listening.
Types
adventures.combat
The fight in an adventure: phantom.aj.adventures.combat. The player's health, weapon and experience as the client keeps them, the client's own targeting, swinging and throwing the way a click does, what is in the air, and the fight's events.
const [phantom] = await combat.near((await quest.playerHitPoint())!, 300);
if (phantom) await combat.strike(phantom.actorId);attack
attack(target: Point, { ranged, ...options }?: ActOptions & { ranged?: boolean | undefined; }) => Promise<{ angle: number; }>Launches the player's weapon at a point, as a click does (QuestManager.playerLaunchWeapon): thrown with ranged, swung otherwise. Resolves with the angle it went at; REFUSED when the client launched nothing (its weapon timer running, no health, no ranged weapon worn).
Parameters
| Name | Type | |
|---|---|---|
target | Point | |
__1 optional | ActOptions & { ranged?: boolean | undefined; } |
Returns
Promise<{ angle: number; }>
Types
clearInFlight
clearInFlight(options?: ActOptions) => Promise<number>Takes every thrown weapon out of the air the way a miss does (QuestProjectile.handleHit with nothing hit) and retires every swing, on this screen only (a miss is never reported). Resolves with how many were retired, once the client's next frames have taken them off its lists.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<number>
Types
effects
effects(userId?: number | undefined) => Promise<AdventurePlayerEffects | null>What the client draws over a player (QuestManager._questPlayersDict, which getQuestPlayerData fills); the player's own when left out. Null outside an adventure and for a player it keeps no data for. Read, never made: asking for a player's data makes it.
Parameters
| Name | Type | |
|---|---|---|
userId optional | number | undefined |
Returns
Promise<AdventurePlayerEffects \| null>
experience
experience(userId?: number | undefined) => Promise<AdventureExperience | null>The player's adventure experience (questXp, questLevel, questXPPercentage), or null.
Parameters
| Name | Type | |
|---|---|---|
userId optional | number | undefined |
Returns
Promise<AdventureExperience \| null>
Types
heal
heal(userId: number, { weaponDefId, ...options }?: ActOptions & { weaponDefId?: number | undefined; }) => Promise<void>Tells the server a healing weapon landed on a player (questPlayerHeal), as the client does for a healing projectile it threw. The weapon is the worn ranged one unless given; REFUSED when there is none. Resolves once the client's message has gone out.
Parameters
| Name | Type | |
|---|---|---|
userId | number | |
__1 optional | ActOptions & { weaponDefId?: number | undefined; } |
Returns
Promise<void>
Types
health
health(userId?: number | undefined) => Promise<number | null>A player's health percentage in the adventure as the client keeps it (AvatarInfo .questHealthPercentage); the player's own when left out. Null when the client has no such player.
Parameters
| Name | Type | |
|---|---|---|
userId optional | number | undefined |
Returns
Promise<number \| null>
hitAt
hitAt(at: Point, radius?: number) => Promise<string | null>The actor a shot landing at a point would hit (QuestManager.projectileRadiusCheck), asked without shooting. Null for none.
Parameters
| Name | Type | |
|---|---|---|
at | Point | |
radius optional | number |
Returns
Promise<string \| null>
Types
inFlight
inFlight() => Promise<AdventureWeaponsInFlight>Every thrown weapon in the air and every swing being played out, read in two collects.
Returns
Promise<AdventureWeaponsInFlight>
inStealth
inStealth() => Promise<boolean>Whether the client counts the player as hidden from phantoms (isPlayerInStealthVolume).
Returns
Promise<boolean>
keepWeaponReady
keepWeaponReady() => Promise<Running>Keeps the weapon ready to go off at once, the game writing its timer back to 0 every frame, until the handle is called. This client's pace only: every hit is still judged by the server.
Returns
Promise<Running>
Types
livePlayers
livePlayers() => Promise<number>How many players the adventure counts as standing (livePlayerCount); 1 when it never says.
Returns
Promise<number>
meleeTargets
meleeTargets(at: Point, radius: number, { attackable, swingId, ...options }?: ActOptions & { attackable?: number | undefined; swingId?: number | undefined; }) => Promise<string[]>The actors a melee swing at a point would hit (QuestManager.meleeRadiusCheck). An act, so it needs game: 'act': each actor it reaches remembers the swing's number (_lastMeleeID) and answers that number once, which is part of how the client's own swings count. A fresh number is used unless given. attackable 1 counts what a melee weapon may hit, 2 what a ranged one may.
Parameters
| Name | Type | |
|---|---|---|
at | Point | |
radius | number | |
__2 optional | ActOptions & { attackable?: number | undefined; swingId?: number | undefined; } |
Returns
Promise<string[]>
Types
near
near(from: Point, radius: number, options?: AdventureTargeting) => Promise<AdventureTarget[]>The phantoms near a point, nearest first, by the client's own targeting (QuestManager.getNearestActivePhantom): on screen, alive, in range, no higher than maxLevel.
Parameters
| Name | Type | |
|---|---|---|
from | Point | |
radius | number | |
options optional | AdventureTargeting |
Returns
Promise<AdventureTarget[]>
Types
nearest
nearest(from: Point, radius: number, options?: AdventureTargeting) => Promise<AdventureTarget | null>The nearest phantom to a point by the client's own targeting, or null.
Parameters
| Name | Type | |
|---|---|---|
from | Point | |
radius | number | |
options optional | AdventureTargeting |
Returns
Promise<AdventureTarget \| null>
Types
nearestPlant
nearestPlant(from: Point, radius: number, { maxLevel }?: { maxLevel?: number | undefined; }) => Promise<AdventureTarget | null>The nearest plant the client would aim a plant weapon at (QuestManager.getNearestPlant).
Parameters
| Name | Type | |
|---|---|---|
from | Point | |
radius | number | |
__2 optional | { maxLevel?: number | undefined; } |
Returns
Promise<AdventureTarget \| null>
Types
playerData
playerData(userId?: number | undefined) => Promise<TypedFlash<QuestPlayerData> | null>The client's own QuestPlayerData for a player (QuestManager._questPlayersDict), held by handle, for drawing over them: its handleHit, handleHealing, levelUp, dropOrb, playStatusText, playItemEmoticonSound. Null when the client keeps none; the caller releases it ($release).
Parameters
| Name | Type | |
|---|---|---|
userId optional | number | undefined |
Returns
Promise<TypedFlash<QuestPlayerData> \| null>
Types
Example
const data = await phantom.aj.adventures.combat.playerData();
await data?.playStatusText('following you');
await data?.$release();report
report(report: CombatReport, options?: ActOptions) => Promise<void>Tells the server something of the fight, as the client's own call for it would, and resolves once that message has gone out. A call the client declines to send (an actor local to this client, _l_…, or no other live player for an actor position) throws TIMEOUT.
Parameters
| Name | Type | |
|---|---|---|
report | CombatReport | |
options optional | ActOptions |
Returns
Promise<void>
Types
Example
await phantom.aj.adventures.combat.report({ kind: 'hit', actorId: 'phantom_1', weaponDefId: 123, at: { x: 400, y: 300 } });requestRespawn
requestRespawn(at?: Point | undefined, options?: ActOptions) => Promise<void>Asks the server to bring the player back after a defeat, as the defeat popup's button does (sendQuestPlayerRequestRespawn), at at or the nearest respawn point. Resolves once the server grants it (qprr).
Parameters
| Name | Type | |
|---|---|---|
at optional | Point | undefined | |
options optional | ActOptions |
Returns
Promise<void>
Types
respawn
respawn(options?: ActOptions) => Promise<Point>Puts the player at the last checkpoint the adventure gave (QuestManager.respawnPlayer), the client's own half of coming back: nothing is sent and no health returns (requestRespawn asks the server). Resolves with the checkpoint; NOT_READY when the adventure has given none.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<Point>
Types
setDisguise
setDisguise(avatarRefId: number | null, { userId, ...options }?: ActOptions & { userId?: number | undefined; }) => Promise<{ userId: number; avatarRefId: number | null; }>Draws a player disguised as one of the adventure's NPCs, or as themselves with null (QuestManager.handleAvSwitch), on this screen only. Confirmed from the client's own record of disguises (_questPlayersSwitched); NOT_READY outside an adventure.
Parameters
| Name | Type | |
|---|---|---|
avatarRefId | number | null | |
__1 optional | ActOptions & { userId?: number | undefined; } |
Returns
Promise<{ userId: number; avatarRefId: number \| null; }>
Types
stats
stats() => Promise<AdventureCombatStats | null>The player's attack and defence range as handleStatsUpdate wrote it onto AvatarInfo.
Returns
Promise<AdventureCombatStats \| null>
Types
strike
strike(actorId: string, options?: ActOptions) => Promise<{ actorId: string; at: Point; }>Swings at an actor the way a click on it does (QuestActor.handleMouseDown at its collision point), so the client's own reach decides. Resolves with where it aimed; REFUSED when the client did not take the click (out of reach, hidden, dead), NOT_READY for an actor the room lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ActOptions |
Returns
Promise<{ actorId: string; at: Point; }>
Types
weapon
weapon({ ranged }?: { ranged?: boolean | undefined; }) => Promise<AdventureWeapon>The weapon the client would fight with (QuestManager.getPlayerActiveWeapon): the strongest worn item of that kind, or the client's own fallback.
Parameters
| Name | Type | |
|---|---|---|
__0 optional | { ranged?: boolean | undefined; } |
Returns
Promise<AdventureWeapon>
Types
whenWeaponReady
whenWeaponReady(options?: ActOptions) => Promise<void>Waits in the game until the weapon will go off again (_playerWeaponTimerProjectile at 0, counted down by the game's own frames). TIMEOUT when it does not in time.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
onAttack
onAttack(listener: (attack: AdventureAttack) => void) => () => voidHears an actor swing at a player (qap).
Parameters
| Name | Type | |
|---|---|---|
listener | (attack: AdventureAttack) => void |
Returns
() => void. Call it to stop listening.
onDefeated
onDefeated(listener: (defeated: { userId: number; }) => void) => () => voidHears a player beaten (qpd); for the player, the defeat popup follows.
Parameters
| Name | Type | |
|---|---|---|
listener | (defeated: { userId: number; }) => void |
Returns
() => void. Call it to stop listening.
onDisguise
onDisguise(listener: (disguise: AdventureDisguise) => void) => () => voidHears a player disguised as an NPC, or the disguise taken off (qavsw).
Parameters
| Name | Type | |
|---|---|---|
listener | (disguise: AdventureDisguise) => void |
Returns
() => void. Call it to stop listening.
onHealth
onHealth(listener: (health: AdventureHealth) => void) => () => voidHears a player's health change, or a player come back (quhp, qrspn).
Parameters
| Name | Type | |
|---|---|---|
listener | (health: AdventureHealth) => void |
Returns
() => void. Call it to stop listening.
onLaunch
onLaunch(listener: (launch: AdventureLaunch) => void) => () => voidHears another player or an actor throw or swing a weapon (qp, qm).
Parameters
| Name | Type | |
|---|---|---|
listener | (launch: AdventureLaunch) => void |
Returns
() => void. Call it to stop listening.
onLevelUp
onLevelUp(listener: (levelUp: AdventureLevelUp) => void) => () => voidHears a player reach a level (qulu).
Parameters
| Name | Type | |
|---|---|---|
listener | (levelUp: AdventureLevelUp) => void |
Returns
() => void. Call it to stop listening.
onPlayerLeft
onPlayerLeft(listener: (left: { userId: number; avatarName: string; }) => void) => () => voidHears a player leave the adventure (qplq).
Parameters
| Name | Type | |
|---|---|---|
listener | (left: { userId: number; avatarName: string; }) => void |
Returns
() => void. Call it to stop listening.
onPlayerRoom
onPlayerRoom(listener: (moved: AdventurePlayerRoom) => void) => () => voidHears another player go to another room of the adventure (qrc).
Parameters
| Name | Type | |
|---|---|---|
listener | (moved: AdventurePlayerRoom) => void |
Returns
() => void. Call it to stop listening.
onRespawnGranted
onRespawnGranted(listener: () => void) => () => voidHears the server let the player come back (qprr).
Parameters
| Name | Type | |
|---|---|---|
listener | () => void |
Returns
() => void. Call it to stop listening.
onSideScroll
onSideScroll(listener: (moved: { userId: number; position: Point; }) => void) => () => voidHears another player move in a side scrolling adventure (qssau).
Parameters
| Name | Type | |
|---|---|---|
listener | (moved: { userId: number; position: Point; }) => void |
Returns
() => void. Call it to stop listening.
Types
onStats
onStats(listener: (stats: AdventureCombatStats) => void) => () => voidHears the player's attack and defence range change (qusu).
Parameters
| Name | Type | |
|---|---|---|
listener | (stats: AdventureCombatStats) => void |
Returns
() => void. Call it to stop listening.
Types
onXp
onXp(listener: (xp: AdventureXp) => void) => () => voidHears the player earn experience (quxp).
Parameters
| Name | Type | |
|---|---|---|
listener | (xp: AdventureXp) => void |
Returns
() => void. Call it to stop listening.
onZap
onZap(listener: (zap: AdventureZap) => void) => () => voidHears a beam or a phantom zap a player (qbzap, qpzap).
Parameters
| Name | Type | |
|---|---|---|
listener | (zap: AdventureZap) => void |
Returns
() => void. Call it to stop listening.
adventures.walk
Walking in an adventure: phantom.aj.adventures.walk. Walks by the room's own grid through the navigation the area was given (AdventureNavigation), following an actor that moves, and chases one that runs. Every walk resolves where it arrived or throws: TIMEOUT short of it, NOT_READY with no navigation or no place to go to, ABORTED when its signal ends (the player stops too).
const reach = await phantom.aj.adventures.actors.reach('chest_3');
await phantom.aj.adventures.walk.to('chest_3', { within: reach?.click ?? 40 });canReach
canReach(target: string | Point, options?: { within?: number | undefined; }) => Promise<WalkReach>Whether the player can get to an actor or a point, asked of the room's grid before a step is taken, with the nearest place they can stand when they cannot. unknown for an actor with no known place.
Parameters
| Name | Type | |
|---|---|---|
target | string | Point | |
options optional | { within?: number | undefined; } |
Returns
Promise<WalkReach>
Types
chase
chase(actorId: string, options?: ChaseOptions) => Promise<ChaseResult>Chases an actor that moves until the player is close enough to act on it, aiming ahead of it, swinging with strike and keeping at it with untilDefeated. Resolves caught, defeated, or gone (it left the room); TIMEOUT (20 seconds by default) when it got away, REFUSED when the room has no way to it.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ChaseOptions |
Returns
Promise<ChaseResult>
Example
const big = await phantom.aj.adventures.actors.biggest();
if (big) await phantom.aj.adventures.walk.chase(big.actorId, { strike: true, untilDefeated: true });distances
distances(actorIds: readonly string[]) => Promise<Record<string, number | null>>How far each actor is on foot, by the room's grid; null for no place or no way there.
Parameters
| Name | Type | |
|---|---|---|
actorIds | readonly string[] |
Returns
Promise<Record<string, number \| null>>
order
order(actorIds: readonly string[]) => Promise<WalkOrder>Actors put in the order that covers them with the least walking, each leg measured from where the last ended; the ones there is no way to are named rather than sorted last.
Parameters
| Name | Type | |
|---|---|---|
actorIds | readonly string[] |
Returns
Promise<WalkOrder>
plan
plan(target: string | Point) => Promise<WalkPlan>The whole way to an actor or a point: the route, how long it is, and what is in the way.
Parameters
| Name | Type | |
|---|---|---|
target | string | Point |
Returns
Promise<WalkPlan>
Types
stop
stop(options?: ActOptions) => Promise<void>Stops the walk under way and the player with it (RoomManagerWorld.forceStopMovement).
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
to
to(actorId: string, options?: AdventureWalkOptions) => Promise<WalkArrival>Walks the player to an actor, reading its place again before each hop so one that moves is followed. lead aims at where it will be. Resolves once within within (40 by default).
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | AdventureWalkOptions |
Returns
Promise<WalkArrival>
toPoint
toPoint(point: Point, options?: AdventureWalkOptions) => Promise<WalkArrival>Walks the player to a point in the room, resolving once within within (40 by default).
Parameters
| Name | Type | |
|---|---|---|
point | Point | |
options optional | AdventureWalkOptions |
Returns
Promise<WalkArrival>
Types
adventures.crystals
An adventure's crystals: the goals they count towards, and the crystals standing in the room: phantom.aj.adventures.crystals. Read from the client every call.
const { goals } = await phantom.aj.adventures.crystals.progress();
for (const goal of goals) console.log(`${goal.colour}: ${goal.current}/${goal.crystals}`);actors
actors(options?: { colours?: readonly ("green" | "yellow" | "blue" | "white" | "purple")[] | undefined; }) => Promise<CrystalActor[]>Every crystal the room holds now, with the colour each fills a goal for, read from the client's own actors since an adventure places its crystals itself and the server never names them. A crystal whose id gives no colour is kept whatever colours asks for.
Parameters
| Name | Type | |
|---|---|---|
options optional | { colours?: readonly ("green" | "yellow" | "blue" | "white" | "purple")[] | undefined; } |
Returns
Promise<CrystalActor[]>
Types
progress
progress() => Promise<CrystalProgress>The crystals gathered and each goal's progress, read from the adventure's own dictionary (gui_goal<n>a needs, gui_goal<n> counts) and _playerOrbCountTotal, measured as QuestManager.handleOrbsUpdate measures them. No goals outside an adventure.
Returns
Promise<CrystalProgress>
onCount
onCount(listener: (count: { crystals: number; }) => void) => () => voidHears every crystal count the server sends (qporbs), lower ones included.
Parameters
| Name | Type | |
|---|---|---|
listener | (count: { crystals: number; }) => void |
Returns
() => void. Call it to stop listening.
onProgress
onProgress(listener: (progress: CrystalProgress) => void) => () => voidHears the crystals go up: each qporbs with a higher count than the last this listener heard (the client keeps only a rising count), with the progress read afresh. Told in order.
Parameters
| Name | Type | |
|---|---|---|
listener | (progress: CrystalProgress) => void |
Returns
() => void. Call it to stop listening.
adventures.treasure
Treasure and items: what can be taken, and taking it the way the client's own clicks do: phantom.aj.adventures.treasure. The player must be close enough for the server to agree; adventures.walk.to gets them there.
for (const actor of await phantom.aj.adventures.treasure.collectables()) {
await phantom.aj.adventures.walk.to(actor.actorId);
await phantom.aj.adventures.treasure.collect(actor.actorId, { keep: { kinds: ['denItem'] } });
}answer
answer(chestId: string, keep: boolean, options?: ActOptions) => Promise<void>Keeps or turns down the prize a chest offered (questActorTreasureTriggered), and shows the chest opened as the popup's buttons do. Resolves once the client's answer has gone out.
Parameters
| Name | Type | |
|---|---|---|
chestId | string | |
keep | boolean | |
options optional | ActOptions |
Returns
Promise<void>
Types
collect
collect(actorId: string, options?: ActOptions & { keep?: TreasureKeep | undefined; }) => Promise<AdventureTaken>Takes what an actor holds the way the client takes its kind: a chest or dropped treasure through its prize popup (keep decides an item; gems and crystals are always kept), an item by picking it up, anything else by setting it off where it stands.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
options optional | ActOptions & { keep?: TreasureKeep | undefined; } |
Returns
Promise<AdventureTaken>
Types
collectables
collectables() => Promise<AdventureActor[]>The chests not opened, dropped treasure not taken and items still lying in the room.
Returns
Promise<AdventureActor[]>
Types
drop
drop(carriedId: string, options?: ActOptions & { at?: Point | undefined; }) => Promise<Point>Drops the item the player carries (sendQuestDropItem), where they stand or at at, and resolves where the server put it down. REFUSED where the adventure allows no drop (QuestManager.allowItemDrop).
Parameters
| Name | Type | |
|---|---|---|
carriedId | string | |
options optional | ActOptions & { at?: Point | undefined; } |
Returns
Promise<Point>
Types
movedItems
movedItems(options?: ActOptions) => Promise<MovedItem[]>Asks where players moved the adventure's items (sendQuestMovedItemsRequest, qmi).
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<MovedItem[]>
Types
open
open(chestId: string, options?: ActOptions) => Promise<TreasureOffer>Opens a chest as clicking it does (QuestActor.handleClick): marks it opened, sends questActorTriggered, takes its click icon away, and resolves with the prize the server offers. REFUSED when the chest did not open (GIVE_FAILED), NOT_READY for a chest not in the room.
Parameters
| Name | Type | |
|---|---|---|
chestId | string | |
options optional | ActOptions |
Returns
Promise<TreasureOffer>
Types
pickUp
pickUp(itemId: string, options?: ActOptions) => Promise<PickedUp>Picks up an item (types 15 and 17) as clicking it does (questPickUpItem), and resolves with the server's answer: picked up, or askToDrop naming what the player already carries. REFUSED when the server refuses, and at once when the player has no health left, as the client refuses.
Parameters
| Name | Type | |
|---|---|---|
itemId | string | |
options optional | ActOptions |
Returns
Promise<PickedUp>
Types
useOn
useOn(targetId: string, carriedId: string, options?: ActOptions & { within?: number | undefined; }) => Promise<Point>Carries the item the player holds to an actor and puts it down there, which is what pouring a watering can into an oasis is. Walks first, and throws rather than dropping it short.
Parameters
| Name | Type | |
|---|---|---|
targetId | string | |
carriedId | string | |
options optional | ActOptions & { within?: number | undefined; } |
Returns
Promise<Point>
Types
onItemGiven
onItemGiven(listener: (given: { actorId: string; }) => void) => () => voidHears the server hand the player an item, which the client picks up at once (qgi).
Parameters
| Name | Type | |
|---|---|---|
listener | (given: { actorId: string; }) => void |
Returns
() => void. Call it to stop listening.
onOffer
onOffer(listener: (offer: TreasureOffer) => void) => () => voidHears each prize a chest offers (qatt), however it was opened.
Parameters
| Name | Type | |
|---|---|---|
listener | (offer: TreasureOffer) => void |
Returns
() => void. Call it to stop listening.
onPickUp
onPickUp(listener: (result: PickUpResult) => void) => () => voidHears what came of every pick up and put down in the adventure, anyone's (qpup).
Parameters
| Name | Type | |
|---|---|---|
listener | (result: PickUpResult) => void |
Returns
() => void. Call it to stop listening.
onReward
onReward(listener: (reward: AdventureReward) => void) => () => voidHears each thing the player came away with, once, from every source: a chest's offer joined to its answer, dropped treasure kept or turned down, an item picked up, a reward screen gift, an award. Names are looked up in the client's definitions, so it is told a moment after, in order.
The offers and spawns it joins are remembered by this listener alone, from when it starts. A discard on the reward screen sends -1 for the gift, so it is not told.
Parameters
| Name | Type | |
|---|---|---|
listener | (reward: AdventureReward) => void |
Returns
() => void. Call it to stop listening.
adventures.rewards
An adventure's reward screens: what the server offers, what the client will let the player take, and taking it the whole way a player does: phantom.aj.adventures.rewards.
const auto = await phantom.aj.adventures.rewards.autoTake({ keep: ['denItem', 'clothing'] });answerGift
answerGift(options?: ActOptions & { keep?: boolean | undefined; }) => Promise<RewardChoice>Answers the gift popup in front of the reward screen with Keep or Turn Down, as its buttons do (onKeepRewardsGift, onDiscardRewardsGift), confirmed by the pick going out.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions & { keep?: boolean | undefined; } |
Returns
Promise<RewardChoice>
Types
autoTake
autoTake(options?: { keep?: RewardKeep | undefined; everyFrames?: number | undefined; pauseMs?: number | undefined; }) => Promise<Running>Empties every reward screen the adventure puts up, for as long as it runs: onScreen and takeScreen together. A screen that fails is logged, and the next one is still taken.
Parameters
| Name | Type | |
|---|---|---|
options optional | { keep?: RewardKeep | undefined; everyFrames?: number | undefined; pauseMs?: number | undefined; } |
Returns
Promise<Running>
Types
choose
choose(index: number, options?: ActOptions & { discard?: boolean | undefined; belowGoal?: boolean | undefined; }) => Promise<RewardChoice>Tells the server which gift was taken (sendPickGiftResult) and nothing else, for a screen that has gone: the screen itself does not learn of it, so use press while it is up. belowGoal is worked out as onKeepRewardsGift does when left out.
Parameters
| Name | Type | |
|---|---|---|
index | number | |
options optional | ActOptions & { discard?: boolean | undefined; belowGoal?: boolean | undefined; } |
Returns
Promise<RewardChoice>
Types
claimable
claimable(offer?: RewardOffer | undefined) => Promise<AdventureGift[]>The gifts the player can take. With the screen up, the screen's own answer (which cannot be wrong about itself); otherwise worked out from the crystal goals reached, one gift per goal in order, or every gift for an adventure with no goals.
Parameters
| Name | Type | |
|---|---|---|
offer optional | RewardOffer | undefined |
Returns
Promise<AdventureGift[]>
closeGoals
closeGoals(options?: ActOptions) => Promise<boolean>Takes the goals screen a reached goal puts up away, so the player can move again, as the client removes it. Nothing is sent: the goal is counted already. Resolves whether one was up.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<boolean>
Types
finish
finish(options?: ActOptions) => Promise<void>Says every gift is picked (sendPickGiftComplete) and takes the screen and any gift popup away as the client does, confirmed by the client's qpgiftdone going out and the screen gone.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
press
press(index: number, options?: ActOptions & { discard?: boolean | undefined; }) => Promise<RewardSlot>Presses one of the screen's treasures the whole way a player does (onAdventureRewardsOptions), waits for the gift popup it opens, and answers it (onKeepRewardsGift, or onDiscardRewardsGift with discard, which only an item allows). Resolves with the treasure once the pick has gone out. NOT_READY with no screen up, REFUSED for a treasure the client will not take.
Parameters
| Name | Type | |
|---|---|---|
index | number | |
options optional | ActOptions & { discard?: boolean | undefined; } |
Returns
Promise<RewardSlot>
Types
screen
screen() => Promise<RewardScreen>The reward screen as the client has drawn it: whether it is up, whether a gift popup is in front of it, and each treasure with whether the client will accept a press on it.
Returns
Promise<RewardScreen>
take
take(options?: ActOptions & { offer?: RewardOffer | undefined; chests?: number | undefined; prefer?: RewardPreference | undefined; pauseMs?: number | undefined; }) => Promise<AdventureGift[]>Takes the treasure an adventure owes and closes its screen: up to chests gifts (every one claimable by default), the kinds in prefer first, larger values first among one kind; none turns them down. The offer is the one given, else the screen up now, else the next offered within timeoutMs. Picks are pauseMs apart on the game's clock, since the server keeps the first of a burst and drops the rest.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions & { offer?: RewardOffer | undefined; chests?: number | undefined; prefer?: RewardPreference | undefined; pauseMs?: number | undefined; } |
Returns
Promise<AdventureGift[]>
Types
takeScreen
takeScreen(options?: ActOptions & { keep?: RewardKeep | undefined; pauseMs?: number | undefined; }) => Promise<RewardSlot[]>Takes everything one reward screen will give up, oldest goal first, reading the screen again between presses (a pick redraws it, and a goal reached meanwhile unlocks another), and makes sure it is gone. keep decides what becomes of an item; gems and crystals are always kept.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions & { keep?: RewardKeep | undefined; pauseMs?: number | undefined; } |
Returns
Promise<RewardSlot[]>
Types
onChoice
onChoice(listener: (choice: RewardChoice) => void) => () => voidHears the player's own gift choice going out, whichever screen it answers.
Parameters
| Name | Type | |
|---|---|---|
listener | (choice: RewardChoice) => void |
Returns
() => void. Call it to stop listening.
onComplete
onComplete(listener: (offer: RewardOffer) => void) => () => voidHears an adventure complete: the first reward screen it offers, once per adventure this listener sees start (qs). Remembered by this listener alone.
Parameters
| Name | Type | |
|---|---|---|
listener | (offer: RewardOffer) => void |
Returns
() => void. Call it to stop listening.
onOffer
onOffer(listener: (offer: RewardOffer) => void) => () => voidHears each reward screen the server offers, with its gifts numbered as choose takes them.
Parameters
| Name | Type | |
|---|---|---|
listener | (offer: RewardOffer) => void |
Returns
() => void. Call it to stop listening.
onScreen
onScreen(listener: (screen: RewardScreen) => void, options?: { everyFrames?: number | undefined; }) => Promise<Running>Hears the reward screen come up, once the client has drawn it, with what it will let the player take. Watched in the game every everyFrames and told only when it appears; watched again after the game reloads the client.
Parameters
| Name | Type | |
|---|---|---|
listener | (screen: RewardScreen) => void | |
options optional | { everyFrames?: number | undefined; } |
Returns
Promise<Running>. Call it to stop listening.
Types
adventures.dialogue
An adventure's talking popup and what else stands in front of the room: phantom.aj.adventures.dialogue.
The popup is QuestManager's own (_talkingPopup), not one of the client's ordinary popups: it darkens behind itself, the player cannot walk while it is up, and the client's own popup closing never sees it. Everything here goes through its own buttons' handlers (onOkBtn, onTalkingPopupClose, onCommandAskConfirm), so what a click would do afterwards still happens.
answer
answer(yes: boolean, options?: ActOptions) => Promise<void>Answers the question the popup is asking (onCommandAskConfirm) and closes it, as its yes and no buttons do. The answer goes to the server when the adventure's script asked it, and that is waited for.
Parameters
| Name | Type | |
|---|---|---|
yes | boolean | |
options optional | ActOptions |
Returns
Promise<void>
Types
answerQuestion
answerQuestion(actorName: string, actorState: number, yes: boolean, options?: ActOptions) => Promise<void>Answers a question the adventure's script asked (QuestXtCommManager.questAskComplete), with the actor and state its ask command carried, and resolves once the answer has gone out. No popup is closed: this is the answer alone.
Parameters
| Name | Type | |
|---|---|---|
actorName | string | |
actorState | number | |
yes | boolean | |
options optional | ActOptions |
Returns
Promise<void>
Types
autoAccept
autoAccept(options?: AutoAcceptOptions) => Promise<Running>Answers the adventure's dialogues as they come up, as a player does: Next until the lines run out, and yes to a question unless answer says otherwise. The game is watched for a popup rather than polled from here, and the watch comes back after a reload.
Parameters
| Name | Type | |
|---|---|---|
options optional | AutoAcceptOptions |
Returns
Promise<Running>
Types
blocking
blocking() => Promise<AdventureBlocker[]>What is in the way of the player, named, in the order it is worth dealing with; empty when nothing is. darkened is only there when it is none of the named screens.
Returns
Promise<AdventureBlocker[]>
close
close(options?: ActOptions) => Promise<boolean>Closes the talking popup with its own close button (onTalkingPopupClose), which undarkens and runs whatever the lines were waiting to do. A question it closes is answered yes, as the client's own close answers it; answer(false) says no. Resolves true once the popup is gone, false when none was up.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<boolean>
Types
current
current() => Promise<AdventureDialogue | null>The talking popup on screen, or null when none is up.
Returns
Promise<AdventureDialogue \| null>
isDarkened
isDarkened() => Promise<boolean>Whether the client has darkened the screen behind something (DarkenManager.isDarkened), which stops the player walking (RoomManagerView.followCursorTest tests it).
Returns
Promise<boolean>
next
next(options?: ActOptions) => Promise<AdventureDialogue | null>Presses Next (onOkBtn): the next page of the lines, or the popup closing on the last. Resolves with the popup as it then stands, or null once it has closed.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<AdventureDialogue \| null>
Types
openPlayers
openPlayers(options?: ActOptions) => Promise<void>Opens the adventure's list of the other players in it (onQuestPlayersBtn), as its HUD button does, and resolves once it is open. NOT_READY outside an adventure; REFUSED when the client closed it again because nobody else is in it.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
show
show(pages: string | readonly string[], options?: { actorId?: string | undefined; title?: string | undefined; } & ActOptions) => Promise<void>Puts up the adventure's talking popup with words of your own (QuestManager.showTalkingDialog), a page a string, with the actor's talking head and title when actorId is given. Resolves once it is on screen. NOT_READY outside an adventure, and while the adventure's own popup or one of its questions is up (closing this one would lose that answer).
Parameters
| Name | Type | |
|---|---|---|
pages | string | readonly string[] | |
options optional | { actorId?: string | undefined; title?: string | undefined; } & ActOptions |
Returns
Promise<void>
Types
onBlocking
onBlocking(listener: (blockers: AdventureBlocker[]) => void, options?: { everyFrames?: number | undefined; }) => Promise<Running>Hears what is in the way change, the first list included: read in the game every few frames and told only when a screen comes or goes. Started again when the game loads the client afresh.
Parameters
| Name | Type | |
|---|---|---|
listener | (blockers: AdventureBlocker[]) => void | |
options optional | { everyFrames?: number | undefined; } |
Returns
Promise<Running>. Call it to stop listening.
Types
adventures.scene
What the adventure shows and plays: phantom.aj.adventures.scene. Sounds and music, the darkness and the torches in it, fades, shakes and films, the clock, the objective line, and the idle timer. Everything here acts on this screen only unless it says it sends.
const awake = await scene.keepAwake();
const lit = await scene.keepLit();
await lit();
await awake();audio
audio() => Promise<AdventureAudio>What the client's sound tables hold now: what plays, and which packs have loaded.
Returns
Promise<AdventureAudio>
darken
darken({ fromScene, ...options }?: ActOptions & { fromScene?: boolean | undefined; }) => Promise<boolean>Puts the adventure's darkness over the room (QuestManager.createDarkness), or, fromScene, only where the room's own scene asks for it (createDarknessFromScene). Resolves whether the room is dark afterwards; darkness already there is left as it is.
Parameters
| Name | Type | |
|---|---|---|
__0 optional | ActOptions & { fromScene?: boolean | undefined; } |
Returns
Promise<boolean>
Types
fade
fade(faded: boolean, options?: ActOptions) => Promise<void>Fades to black or back with the client's own fader (handleFade(false) to fade out, _faderState 4 to take the sheet down, as a film ending does). NOT_READY while a film plays, whose fader it is, and when fading back with nothing faded.
Parameters
| Name | Type | |
|---|---|---|
faded | boolean | |
options optional | ActOptions |
Returns
Promise<void>
Types
fallingPhantoms
fallingPhantoms() => Promise<AdventureFallingPhantom[]>The phantoms the adventure is raining down now (QuestManager._fallingPhantoms).
Returns
Promise<AdventureFallingPhantom[]>
finishCutscene
finishCutscene(options?: ActOptions) => Promise<void>Tells the server the adventure's film is finished (sendPlaySwfComplete), which its script waits for. Resolves once the message has gone out.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
keepAwake
keepAwake() => Promise<Running>Keeps the client's idle timer at 0 (QuestManager._gameIdleTimer), the game writing it every frame, so the adventure never warns the player for sitting still nor puts them out at five minutes. Until the handle is called; the count then starts from 0.
Returns
Promise<Running>
Types
keepLit
keepLit() => Promise<Running>Keeps every room's darkness hidden (_darknessMask.visible held false, the new mask of each room included) until the handle is called. This screen only.
Returns
Promise<Running>
Types
lighten
lighten(options?: ActOptions) => Promise<void>Takes the darkness away (QuestManager.removeDarkness), confirmed gone.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
loop
loop(name: string, options?: ActOptions) => Promise<Running>Starts a sound looping (QuestManager.playLoopingSound) until the handle is called, which stops it (stopLoopingSound). REFUSED when the client played nothing, a name no pack has loaded.
Parameters
| Name | Type | |
|---|---|---|
name | string | |
options optional | ActOptions |
Returns
Promise<Running>
Types
musicStream
musicStream(name: string) => Promise<AdventureMusicStream>One of the adventure's music streams by the name playMusic takes.
Parameters
| Name | Type | |
|---|---|---|
name | string |
Returns
Promise<AdventureMusicStream>
objective
objective() => Promise<string>The objective line on the HUD as the player reads it (GuiHud.questObjectiveTxt); '' for none.
Returns
Promise<string>
playMusic
playMusic(name: string, options?: ActOptions) => Promise<void>Changes the adventure's music (QuestManager.playMusic), fading out what plays; '0' is silence. Resolves once the client names it as playing (_currentMusic).
Parameters
| Name | Type | |
|---|---|---|
name | string | |
options optional | ActOptions |
Returns
Promise<void>
Types
playSound
playSound(name: string, options?: AdventureSoundOptions & ActOptions) => Promise<void>Plays one of the adventure's own sounds by name (QuestManager.playSound). The client holds a sound down for half a second, so asking twice in a row plays it once.
Parameters
| Name | Type | |
|---|---|---|
name | string | |
options optional | AdventureSoundOptions & ActOptions |
Returns
Promise<void>
Types
setActorTorch
setActorTorch(actorId: string, lit: boolean, options?: ActOptions) => Promise<void>Lights or puts out an actor's torch (QuestManager.handleQuestTorch), as the adventure's own qtorch does. Confirmed on its dictionary entry (torchEnabled); NOT_READY for an actor the adventure lacks.
Parameters
| Name | Type | |
|---|---|---|
actorId | string | |
lit | boolean | |
options optional | ActOptions |
Returns
Promise<void>
Types
setTimeLeft
setTimeLeft(seconds: number, options?: ActOptions) => Promise<number>Sets the clock the client counts down (_guiTimerLocal). At 0 the client itself tells the server the time is up (gui_time_min) as running out does. NOT_READY when no clock runs.
Parameters
| Name | Type | |
|---|---|---|
seconds | number | |
options optional | ActOptions |
Returns
Promise<number>
Types
shake
shake(milliseconds: number, options?: ActOptions) => Promise<void>Shakes the room (QuestManager.handleShake) for that long, confirmed by its shake clock.
Parameters
| Name | Type | |
|---|---|---|
milliseconds | number | |
options optional | ActOptions |
Returns
Promise<void>
Types
showObjective
showObjective(stringId: number, options?: ActOptions) => Promise<void>Puts an objective on the HUD by its localisation id (QuestManager.commandNotify), with the chime, as the script's notify does. This screen only; confirmed on _questObjectiveText.
Parameters
| Name | Type | |
|---|---|---|
stringId | number | |
options optional | ActOptions |
Returns
Promise<void>
Types
stopShaking
stopShaking(options?: ActOptions) => Promise<boolean>Stops the room shaking now and puts the background back (_shaketimer emptied, then stopShake). Resolves whether it was shaking.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<boolean>
Types
timeLeft
timeLeft() => Promise<number | null>Seconds left on an adventure clock the client counts itself (QuestManager._guiTimerLocal); null when none runs.
Returns
Promise<number \| null>
torch
torch(lit: boolean, { userId, ...options }?: ActOptions & { userId?: number | undefined; }) => Promise<void>Gives a player a torch in the darkness, or takes it away (QuestManager.addTorch, removeTorch, at the client's own scale and offset). The player's own unless userId. Confirmed in the client's list of lights; REFUSED with no darkness to light.
Parameters
| Name | Type | |
|---|---|---|
lit | boolean | |
__1 optional | ActOptions & { userId?: number | undefined; } |
Returns
Promise<void>
Types
torches
torches() => Promise<AdventureTorchLight[]>Every light the client has cut in the darkness, in its own order; empty with no darkness.
Returns
Promise<AdventureTorchLight[]>
onEffect
onEffect(listener: (effect: AdventureEffect) => void) => () => voidHears everything the adventure does to the screen and the speakers: sounds and voice overs, music, sound packs, fades, shakes, films and their preloads, torches, and the page views it records for Animal Jam. One listener, one payload per message, bundled ones included.
Parameters
| Name | Type | |
|---|---|---|
listener | (effect: AdventureEffect) => void |
Returns
() => void. Call it to stop listening.
Example
const stop = phantom.aj.adventures.scene.onEffect((effect) => {
if (effect.kind === 'voiceOver') console.log(effect.subtitle);
});onObjective
onObjective(listener: (objective: AdventureObjective) => void) => () => voidHears each objective the adventure's script sets (qcmd notify), translated, in the order they came. One showObjective puts up is the client's own and is not heard.
Parameters
| Name | Type | |
|---|---|---|
listener | (objective: AdventureObjective) => void |
Returns
() => void. Call it to stop listening.
adventures.garden
Seeds and the plants they grow into, in the adventures that use them: phantom.aj.adventures.garden.
const spot = (await quest.player()).position!;
if (await garden.canPlant(spot)) await garden.plant(564, spot);canPlant
canPlant(at: Point) => Promise<boolean>Whether a seed may be planted at a point (QuestManager.validatePlantSeedLocation): inside a planting volume and not too near another plant. The client's own check; nothing is sent.
Parameters
| Name | Type | |
|---|---|---|
at | Point |
Returns
Promise<boolean>
Types
feed
feed(plantId: string, phantomId: string, at: Point, options?: ActOptions) => Promise<void>Feeds a phantom to a plant (sendEatPhantom), as the plant's own touch does, and resolves once the server says the plant ate it (qpa).
Parameters
| Name | Type | |
|---|---|---|
plantId | string | |
phantomId | string | |
at | Point | |
options optional | ActOptions |
Returns
Promise<void>
Types
plant
plant(defId: number, at: Point, options?: ActOptions) => Promise<AdventurePlanted>Plants a seed at a point (sendPlantSeed), as dragging one onto a valid spot does, and resolves with the plant once the server says it took root for this player. REFUSED when the server turns it down (canPlant is the client's own check first).
Parameters
| Name | Type | |
|---|---|---|
defId | number | |
at | Point | |
options optional | ActOptions |
Returns
Promise<AdventurePlanted>
Types
plants
plants() => Promise<AdventureActor[]>The plants in the room (actor type 21), as the client holds them.
Returns
Promise<AdventureActor[]>
Types
satchel
satchel() => Promise<AdventureSeedSatchel>The seed satchel as the client holds it; open false outside a seed adventure.
Returns
Promise<AdventureSeedSatchel>
seeds
seeds() => Promise<AdventureSeed[]>The seeds the player holds, with how many and the most they may carry, read from the client.
Returns
Promise<AdventureSeed[]>
onPlantAte
onPlantAte(listener: (ate: { plantActorId: string; phantomActorId: string; }) => void) => () => voidHears a plant eat a phantom (qpa).
Parameters
| Name | Type | |
|---|---|---|
listener | (ate: { plantActorId: string; phantomActorId: string; }) => void |
Returns
() => void. Call it to stop listening.
onPlanted
onPlanted(listener: (planting: AdventureSeedPlanting) => void) => () => voidHears a seed take root, or be refused, for anybody in the adventure (qps).
Parameters
| Name | Type | |
|---|---|---|
listener | (planting: AdventureSeedPlanting) => void |
Returns
() => void. Call it to stop listening.
onRecoil
onRecoil(listener: (recoil: { actorId: string; }) => void) => () => voidHears a plant recoil after eating (qepr).
Parameters
| Name | Type | |
|---|---|---|
listener | (recoil: { actorId: string; }) => void |
Returns
() => void. Call it to stop listening.
onSeeds
onSeeds(listener: (seed: AdventureSeed) => void) => () => voidHears the player's count of a seed change (qseed); defId 0 empties every seed.
Parameters
| Name | Type | |
|---|---|---|
listener | (seed: AdventureSeed) => void |
Returns
() => void. Call it to stop listening.
adventures.routes
Recording what the player's client asks of an adventure's actors, and playing it back: phantom.aj.adventures.routes.
A route is plain JSON a plugin can keep. Playing it back matches each step to the actor standing where the recorded one stood (matchRouteStep, which says why ids alone will not do), waits for the room it belongs to, walks to what has to be touched, and gives every step a named outcome: the client sends qat for any string and the server answers a bad one with silence, so nothing here is skipped quietly.
const recorder = phantom.aj.adventures.routes.record();
await recorder.stop();
const playing = await phantom.aj.adventures.routes.play(recorder.route());
const playback = await playing.done;match
match(step: AdventureRouteStep, options?: { within?: number | undefined; bound?: ReadonlyMap<string, string> | undefined; }) => Promise<RouteMatch>The actor a recorded step would be played on now, or the named reason there is none: the room is wrong, the chest already opened, nothing of the kind left standing.
Parameters
| Name | Type | |
|---|---|---|
step | AdventureRouteStep | |
options optional | { within?: number | undefined; bound?: ReadonlyMap<string, string> | undefined; } |
Returns
Promise<RouteMatch>
play
play(route: AdventureRoute, options?: PlayRouteOptions) => Promise<AdventurePlaying>Plays a recorded route back: each step in order, on the actor standing where the recorded one stood, in the room it belongs to. It waits for that room (the server moves the party), keeps the client from timing the player out (scene.keepAwake), walks to chests, items and crystals, and paces treasure as the server needs. Resolves once started; done resolves with every step's outcome. REFUSED while another playback runs.
Parameters
| Name | Type | |
|---|---|---|
route | AdventureRoute | |
options optional | PlayRouteOptions |
Returns
Promise<AdventurePlaying>
record
record() => AdventureRecorderRecords what the player's client asks of actors from now on, until stopped. The adventure and its difficulty are read from the client as the recording starts, or at its first step when it started outside one. route() gives the steps as plain JSON, during or after.
Returns
AdventureRecorder
onStep
onStep(listener: (step: AdventureStep) => void) => () => voidHears each thing the player's client asks of an actor (qat, qpup, qatt), whether the player clicked or a script did, with where the player and the actor stood, read just after the message passed. Told in the order the client sent them.
Parameters
| Name | Type | |
|---|---|---|
listener | (step: AdventureStep) => void |
Returns
() => void. Call it to stop listening.
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.
RunningAdventure
The adventure the client has running, as QuestManager records it.
| Field | Type | |
|---|---|---|
scriptDefId | number | The script running (_questScriptDefId), which lobby.definition describes. |
difficulty | number | 0 normal, 1 hard (_questDifficultyLevel). |
startingPlayerCount | number | How many players it began with (_questStartingPlayerCount). |
timeStamp | string | null | The stamp the server put on the script (_questScriptTimeStamp); null for none. |
room | string | null | The room the player is in, such as quest_039.room_2 (SFClient._currRoom.name). |
type | number | The kind the adventure names itself, 1 to 9 (getAdventureType); 0 for none. 7 is Bitter Sweets. |
sideScroll | boolean | The room scrolls sideways and is played as a platformer (isSideScrollQuest). |
playAsPet | boolean | Played as a pet (isBeYourPetQuest). |
joinableAfterStart | boolean | Players may join after it started (isDynamicallyJoinableQuest). |
likeNormalRoom | boolean | The room behaves as an ordinary room (isQuestLikeNormalRoom). |
AdventureStatus
The client's own bookkeeping of the adventure it is in, read in one go.
| Field | Type | |
|---|---|---|
inAdventure | boolean | The client counts itself in an adventure room (_inQuestRoom). |
justJoined | boolean | The player has only just joined the adventure's room (hasJustJoinedQuest). |
exitPending | boolean | The client is on its way out, waiting for the room change (questExitPending). |
throwKeyDown | boolean | The throw key is held down (projectileKeyDown). |
paused | boolean | The adventure's frame has stopped (_paused), which it does as it unloads. |
sceneLoaded | boolean | The room's scene has loaded (_sceneLoaded). |
crystalCount | number | The crystals the client counts for the player (getPlayerCrystalCount). |
maxGoals | number | The most crystal goals an adventure of this kind has (getMaxQuestGoal). |
idleSeconds | number | Seconds the player has sat still (_gameIdleTimer): warned at 240, sent out at 300. |
AdventurePhase
Where a run stands: outside one, waiting in a lobby, playing, or on its reward screen.
type AdventurePhase = 'idle' | 'lobby' | 'playing' | 'rewards'AdventureStart
The adventure as it started, as the server's start message (qs) lists it.
| Field | Type | |
|---|---|---|
scriptDefId | number | |
playerCount | number | |
timestamp | string | The stamp the server put on the script. |
actors | { actorId: string; type: number; defId: number | null; defName: string | null; state: number; visible: boolean; requireClick: boolean; pathName: string; swfState: string; }[] | Every actor the adventure starts with, as the server listed them. |
AdventureEnd
The player out of an adventure, into a room outside it.
| Field | Type | |
|---|---|---|
scriptDefId | number | null | The adventure, or null when the listener started after it began and the client had forgotten. |
reason | AdventureEndReason | |
room | string | The room the player came out into. |
AdventureEndReason
Why the player is out of an adventure.
type AdventureEndReason = | 'exit-command'
/** The server sent the player out (`qxt`). */
| 'sent-out'
/** The player left, or was moved to a room outside the adventure otherwise. */
| 'left'AdventurePhaseChange
One move from one phase to the next.
| Field | Type | |
|---|---|---|
phase | AdventurePhase | "ended" | |
was | AdventurePhase | "ended" | |
scriptDefId | number | null | |
reason | AdventureEndReason | null | Why it ended, on ended; null otherwise. |
at | number | When, in milliseconds since 1970. |
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 |
AdventureClientCall
One of those steps, as it happened.
| Field | Type | |
|---|---|---|
step | "started" | "playerAttacked" | "actorDeath" | "actorHealthStatus" | "healthUpdate" | "swipe" | "projectile" | "beamZap" | "phantomZap" | "actorAttackReported" | "phantomZapReported" | "destructibleAttacked" | "actorSeekRequested" | "weaponThrown" | "weaponSwung" | "playerDead" | "respawnRequested" | "statsUpdate" | "levelUp" | "xpUpdate" | "award" | "gemsTallied" | "spawn" | "spawnPlaced" | "spawnPlacedAtRoot" | "actorRoster" | "actorStatus" | "sceneAssets" | "roomJoined" | "playerJoined" | "roomChange" | "playerLeft" | "playerLeftTextDone" | "exitRoom" | "exitPressed" | "exitByType" | "roomMissing" | "actorPath" | "volumeProgress" | "treasureTriggered" | "itemPickedUp" | "itemsMoved" | "actorRestored" | "crystalGoals" | "seedGiven" | "seedPlanted" | "plantAte" | "plantRecoiled" | "fallingPhantoms" | "fallingPhantomCrossing" | "frame" | "fadeIn" | "fadeEnded" | "shakeStarted" | "shakeStep" | "lightFinished" | "cutsceneAsked" | "cutscenePreloaded" | "cutscenePlayed" | "actorSwfState" | "mediaLibrary" | "voiceOverEnded" | "levelShape" | "dialogueResized" | "pageOpened" | "assetTaken" | "assetPooled" | "questEvent" | "keyDown" | "keyUp" | "mousePressed" | "giftOffered" | "rewardScreenDrawn" | "rewardScreenRefreshed" | "rewardPressed" | "rewardPressedNonMember" | "rewardKept" | "rewardDiscarded" | "giftClosed" | "defeatAnswered" | "dropAnswered" | "leaveAnswered" | "leaveLobbyAnswered" | "leaveLobbyAsked" | "scriptPopupAnswered" | "scriptPopupYes" | "scriptPopupNo" | "scriptPopupOk" | "rewardScreenPressed" | "idleWarningAnswered" | "playerSelected" | "joinScreenOpened" | "joinScreenClosed" | "listOpened" | "listClosed" | "listWindowsLoaded" | "listRowPressed" | "privateLobbyMoved" | "adventureListLoaded" | "platformerListLoaded" | "rewardScreenLoaded" | "goalRewardScreenLoaded" | "rewardIconLoaded" | "dialogueLoaded" | "dialogueHeadLoaded" | "timerLoaded" | "hotColdLoaded" | "goalLoaded" | "levelShapeLoaded" | "fallingPhantomLoaded" | "cutsceneLoaded" | "soundsLoaded" | "globalSoundsLoaded" | "reportWindowsLoaded" | "awardPictureShown" | "awardPictureRemoved" | "newPlayerSkipped" | "newPlayerEditorReady" | "newPlayerShopOpened" | "newPlayerShopClosed" | "minigameCommand" | "setStateCommand" | "npcState" | "npcTurned" | "npcAnimation" | "npcSwfState" | "npcHealthBar" | "npcHitText" | "npcReady" | "npcArtLoaded" | "npcSecondaryArtLoaded" | "npcReset" | "npcBuilt" | "npcDestroyed" | |
args | Record<string, unknown> | The arguments, by the names the client's own hook table carries for them. |
argList | unknown[] | The same in the order the method takes them. |
phase | "enter" | "exit" | Whether this is the call starting or returning. |
at | number | When it was heard, in milliseconds since 1970. |
ClientStepOptions
Which calls of a step to hear.
| Field | Type | |
|---|---|---|
every optional | number | undefined | Only every nth call: frame runs two dozen times a second. Every call by default. |
phase optional | "enter" | "exit" | undefined | Hear the call starting (the default) or returning. |
AdventureDefinition
| Field | Type | |
|---|---|---|
defId | number | |
titleStrId | number | The localisation id of its title, which phantom.localization translates. |
descStrId | number | |
avatarLimit | number | |
avatarMin | number | |
avatarType | number | |
difficulty | number | Nonzero when the adventure offers a hard mode. |
levelMin | number | |
mediaRefId | number | |
bannerMediaRefId | number | |
time | number | 1 for an adventure players can join after it started. |
hudType | number | |
membersOnly | boolean | |
playAsPet | boolean | |
restrictions | number | |
avatarDefFlags | number | |
isPlatformer | boolean |
AdventureLobby
The lobby the player waits in before an adventure starts, as the client has it on screen.
| Field | Type | |
|---|---|---|
kind | AdventureLobbyKind | |
scriptDefId | number | null | |
difficulty | number | null | 0 normal, 1 hard; null for a lobby that does not say (the host's own). |
waitingUserIds | number[] | The players waiting, by their ids in the room, as the server last listed them (qw). The client draws the list and keeps nothing of it, so the area keeps the last one it heard; empty before one has come since the area was made. |
AdventureLobbyKind
How the player came to wait in a lobby: a public one, their own, or somebody else's private one.
type AdventureLobbyKind = 'public' | 'hosting' | 'private'AdventureWindow
An adventure's join window: the public one, or one the player hosts.
| Field | Type | |
|---|---|---|
ready | boolean | |
kind | "public" | "private" | |
mode | "normal" | "custParty" | "custSettings" | "noPlayers" | |
scriptDefId | number | |
title | string | |
description | string | |
hard | boolean | |
places | number | How many players it takes, drawn as places. |
players | string[] | The players in it now. |
canPlay | boolean |
AdventureLobbyJoin
A lobby joined or opened: what the server's answer said.
| Field | Type | |
|---|---|---|
kind | AdventureLobbyKind | |
scriptDefId | number | |
difficulty | number | null | 0 normal, 1 hard; null on qjc, whose answer does not carry it. |
AdventureJoinOptions
Joining, with the difficulty to join at.
type AdventureJoinOptions = ActOptions & {
/** 0 normal (the default), 1 hard. */
difficulty?: number;
}AdventureJoinAnswer
The server's answer to a join, host or private join, as onJoin hears it.
type AdventureJoinAnswer = | (AdventureLobbyJoin & { joined: true })
| {
kind: AdventureLobbyKind;
joined: false;
/** The refusal code: `FULL`, `NM` (not a member), `NL` (level), `NV`... */
refusal: string;
/** What came with it: the level needed for `NL`, the restriction for `NA`. */
extra: string[];
}AdventureActor
One actor as the client holds it now: a QuestActor in QuestManager._questActors, with its entry in the adventure's dictionary (_actorData). Every actor the room has drawn is one of these: the chests, items, crystals, phantoms and volumes the script placed, and what spawned since.
| Field | Type | |
|---|---|---|
actorId | string | |
type | number | null | QuestActor.QUEST_ACTOR_TYPE_*: 13 a placed chest, 15 and 17 items, 200 dropped treasure. |
kind | AdventureActorKind | null | The client's own word for the type; null for a number the build does not name. |
defId | number | null | |
state | number | null | The state the adventure's script has it in (_actorData.state). |
status | number | _actorData.status: 0 until it is opened or used, as a chest's click sets it to 1. |
pickedUp | boolean | Dropped treasure that was taken (_actorData.pickedUp). |
visible | boolean | Whether the client is showing it: both its own flag (_visible) and its display object's. |
requireClick | boolean | Whether it needs a click rather than a walk into it (_requireClick). |
clickable | boolean | Whether its click icon is up now, so the player could click it (_clickIcon.visible). |
healthPercent | number | null | What the server last said is left of it, for an actor that fights; null for one it has not. |
position | Point | null | Where its display object stands. |
group | string | null | The group its id puts it in (<group>__<n>), or null. |
prize | AdventureActorPrize | null | What dropped treasure holds; null for anything else. |
Point
A point in the room or on the stage, in pixels. One type for every area.
| Field | Type | |
|---|---|---|
x | number | |
y | number |
AdventureActorPrize
What dropped treasure holds, as the client spawned it (QuestManager.handleSpawn).
| Field | Type | |
|---|---|---|
kind | AdventurePrizeKind | null | |
subType | number | The QUEST_PRIZE it carries (_actorData.subType). |
defId | number | null | The den item's or clothing item's definition id. |
color | number | null | A clothing item's colour (_actorData.itemData). |
amount | number | null | Gems or crystals (_actorData.gems). |
AdventureActorEntry
One actor's entry in the adventure's own dictionary (QuestManager._questActorDictionary), which holds every actor of the adventure: the drawn ones, and the variables, timers and gui_* proxies the room never draws.
| Field | Type | |
|---|---|---|
actorId | string | |
type | number | null | |
kind | AdventureActorKind | null | |
defId | number | null | |
state | number | null | The state the script set (state); a variable's value, a goal's count. |
visible | boolean | |
requireClick | boolean | |
pathName | string | null | |
progress | number | null | A volume's progress, 0 to 100, as the server last said (qviu); null for none. |
iconShowing | boolean | null | Whether its "look here" icon is up, as the script last set it (qicon). |
torchEnabled | boolean | null | Whether its torch is lit, as the script last set it (qtorch). |
TypedFlash
A place in Flash whose declared type is T.
type TypedFlash<T> = FlashPlace<T> &
FlashConstructor<T> &
(unknown extends T
? unknown
: {
readonly [Key in keyof T as Key extends `$${string}` ? never : Key]: T[Key] extends (
...args: infer Args
) => infer Result
? FlashMethod<Args, Result>
: TypedFlash<T[Key]>;
})FlashRead
What reading a place of type T resolves with.
type FlashRead<T> = unknown extends T
? FlashData
: T extends Primitive
? T
: T extends readonly (infer Item)[]
? FlashRead<Item>[]
: T extends (...args: never[]) => unknown
? TypedFlash<unknown>
: TypedFlash<T>FlashWrite
What may be given where Flash expects T.
type FlashWrite<T> = unknown extends T
? FlashArgumentLike
: T extends Primitive
? T
: T extends readonly (infer Item)[]
? FlashWrite<Item>[]
: T extends (...args: never[]) => unknown
? ((...args: FlashData[]) => void) | FlashCallback
: TypedFlash<T> | FlashHandle | FlashArgumentLikeHoldOptions
How a hold behaves.
| Field | Type | |
|---|---|---|
everyFrames optional | number | undefined | Write on every nth frame. Every frame by default, which is what a value the client resets needs. |
when optional | "enter" | "exit" | undefined | Which half of the frame to write in. 'enter' by default, before the frame is read. Use 'exit' for a member the game writes every frame of its own, such as a thing it pins to the pointer. Two objects' enter-frame listeners have no order between them, so an ordinary hold on one of those stands only on the frames the loader happens to run second, and the value flickers or never takes at all. Exit-frame work runs after every enter-frame listener, so what is held is what is drawn and what the next frame reads. |
while optional | HookWhen | undefined | Only while this holds, in the same rules as a hook's when, read between calls. |
once optional | boolean | undefined | Write once, on the first frame the condition holds, then stop. |
restore optional | boolean | undefined | Put back what was there before the first write when the hold ends. On by default. |
onFailed optional | ((error: string) => void) | undefined | Called if the game turns the hold off because a write failed. |
HookTest
A condition. Made by phantom.flash.rules.
| Field | Type | |
|---|---|---|
__@TEST@169973 | RawTest |
FlashArgumentLike
Anything the bridge carries, typed places included.
type FlashArgumentLike = FlashArgument | TypedFlash<unknown> | FlashArgumentLike[] | { [key: string]: FlashArgumentLike }FlashPlace
The operations every place has, whatever its type.
| Field | Type | |
|---|---|---|
$get | () => Promise<FlashRead<T>> | Reads the value here: plain data as it is, an object as a typed place held by handle. |
$set | (value: FlashWrite<T>) => Promise<void> | Writes the value here, once. The client may put its own back a frame later: a member it sets every frame, or on every redraw, or an object it builds again for the next room. For a change that has to stay, use $keep. |
$keep | (value: FlashWrite<T>, options?: HoldOptions | undefined) => Promise<() => Promise<void>> | Writes the value here and keeps it here, until the function it gives back is called, which puts back what was there. It is $set for a change that has to last. The game writes it itself, every frame, so a value the client puts back is overwritten before Flash draws it. The place is followed rather than pinned: nothing is lost when the object is not there yet (it is written as soon as it is) or when the client builds it again (the new one is written too). It is phantom.flash.hold on this place, and takes the same options. ts const hud = phantom.flash.use('gui.GuiManager').mainHud; const faded = await hud.alpha.$keep(0.5); |
$call | (...args: FlashArgumentLike[]) => Promise<FlashData> | Calls what is here, whatever the declarations say is at this place. A place is callable in its own right (avatars.createAvatar(id, x, y, name)), which is how to write a call the declarations describe: the arguments and the answer are both checked. This is the same call for the places they cannot describe, and it saves casting one to reach it: - a class whose instance side declares nothing, because every member of it is static (gui.EmoticonUtility), so $as and a hook's self give a place with no members; - an object the client typed as Object or *, or one reached with $at; - a member holding a function, such as a callback the client keeps in a field. It answers FlashData, since there is no declared return to read it as. ts const emotes = phantom.flash.use('gui.EmoticonUtility'); console.log(await emotes.stringForId(3)); console.log(await emotes.$at('stringForId').$call(3)); |
$listen | (event: string, listener: (event: FlashData, keep: <Kept>(value: Kept) => Kept) => void, options?: { read?: readonly (readonly string[])[] | undefined; capture?: boolean | undefined; } | undefined) => Promise<() => Promise<void>> | Listens for an event on the object here. Resolves with what stops listening. Without read, the event is its readable members, objects among them as typed places held by handle, and every one of them is released once the listener returns, except those passed to keep before then (release those with $release when done). read names the paths to read as the event is dispatched instead: the event is then { className, type, read } with the values in that order, and nothing is held. A listener that ignores the event passes read: []. capture listens on the way down. Both are FlashBridge.listen's options. ts await stage.$listen('mouseMove', (event) => console.log((event as { read: number[] }).read), { read: [['stageX'], ['stageY']], }); |
$describe | () => Promise<FlashValue> | The public members of what is here, as Flash's describeType lists them. |
$at | (...path: string[]) => AnyFlash | Further along, by names the types do not know: untyped from here on. |
$as | { <Name extends keyof ClientInstances & string>(name: Name): TypedFlash<ClientInstances[Name]>; (name: string): AnyFlash; } | The same place, read as the client's name from here on. Nothing is sent and nothing is checked in the game: it says what the object here is, so the editor completes and checks its members again after a step the declarations could not follow ($at, a hook's capture, anything the client typed as Object or *). Naming the wrong class is not caught here; the read or call that follows is what fails. ts const grid = phantom.flash .use('gui.AvatarEditor') .$at('_colorTableColor1') .$as('gui.ColorTable'); console.log(await grid._numCols.$get(), 'by', await grid._numRows.$get()); |
$release | () => Promise<void> | Releases the object this place is held by, when it is one; nothing otherwise. |
$reference | FlashReference | The untyped reference underneath. |
FlashValue
A value on the TypeScript side: plain data, undefined, or a handle to an object in Flash.
type FlashValue = | null
| undefined
| boolean
| number
| string
| FlashValue[]
| { [key: string]: FlashValue }
| FlashHandleFlashArgument
What may be passed to Flash: a value, a function Flash may call, or an object to make there.
type FlashArgument = | FlashValue
| FlashArgument[]
| { [key: string]: FlashArgument }
| ((...args: FlashValue[]) => void)
| FlashNewFlashData
Plain data read from Flash, with objects that live there as typed places.
type FlashData = | null
| undefined
| boolean
| number
| string
| FlashData[]
| { [key: string]: FlashData }
| TypedFlash<unknown>AnyFlash
A place whose class the declarations do not describe: phantom.flash.use('a.Class') for a class the client has no declaration for, $at, $as with a name, or anything read back from one.
Every member is another place of the same kind, and every place can be called, which is what reflection allows and what a place does at run time. Nothing is checked, because there is nothing to check it against: a name the game does not have fails when it is used, not here. then is left out, so awaiting a place is still the mistake it always was.
type AnyFlash = FlashPlace<unknown> &
FlashMethod<unknown[], unknown> & {
readonly [member: string]: AnyFlash;
} & { then?: undefined }FlashMethod
A method of the client, called with checked arguments.
type FlashMethod<Args extends readonly unknown[], Result> = (
...args: { [Index in keyof Args]: FlashWrite<Args[Index]> }
) => Promise<FlashRead<Result>>FlashConstructor
A class's constructor, from its declared $new.
type FlashConstructor<T> = T extends { $new(...args: infer Args): infer Instance }
? { $new: FlashMethod<Args, Instance> }
: unknownActorReach
How close the player has to be to act on an actor, and where to aim.
| Field | Type | |
|---|---|---|
actorId | string | |
radius | number | How wide the actor is for a collision (QuestActor.collisionRadiusMoving). |
click | number | How close a click on it has to be made from: radius plus 1.75 avatars (handleMouseDown). |
swing | number | How close a walked-up swing goes off: radius plus 1.5 avatars (onRadiusTest). |
touch | number | How close counts as touching it: radius plus one avatar (actorCollisionTest). |
at | Point | Where to aim: its place plus actorOffset (the NPC view's collisionMovingPoint). |
distance | number | null | Pixels from the player's hit point to at; null when the player could not be placed. |
inReach | boolean | Whether a click would land now. |
touching | boolean | Whether the player is inside the touch circle now, by the reading. |
AdventureNpcDefinition
A phantom's or a friendly NPC's definition, as the server sent it and the client keeps it in QuestManager._npcDefs (QuestXtCommManager.questNPCDefResponse builds each one).
| Field | Type | |
|---|---|---|
defId | number | |
titleStrId | number | The localisation id of its name, which the HUD translates. |
type | number | Its kind, as the actors are typed: 11 an attacker, 21 a plant, 1 a plain NPC. |
hps | number | What it can take before it dies, and what it shrugs off with each hit. |
defense | number | |
xpValue | number | The experience the player is given for defeating it. |
level | number | |
attackable | number | 1 melee, 2 ranged, 3 either, 0 not at all: how a player may attack it. |
damageTouch | number | Above 0 when touching it hurts. |
avatarRefId | number | |
mediaRefId | number | |
headMediaRefId | number | |
iconMediaRefId | number |
ActorQuery
Which actors a search counts. Every field given has to be answered, so they narrow together: { kinds: ['attacker'], minLevel: 4, within: 400 } is the phantoms of level 4 or better within 400 pixels. Nothing here is a function, so a query crosses to a plugin as plain data.
| Field | Type | |
|---|---|---|
ids optional | readonly string[] | undefined | Exactly these actor ids. |
name optional | string | undefined | A pattern over the id, * any run of characters and ? one, without regard to case. |
group optional | string | undefined | The group its id puts it in (<group>__<n>). |
kinds optional | readonly AdventureActorKind[] | undefined | The client's words for the kinds wanted. |
types optional | readonly number[] | undefined | QUEST_ACTOR_TYPE_* numbers. |
defIds optional | readonly number[] | undefined | NPC definition ids. |
minLevel optional | number | undefined | Its definition's level, at least this and at most that. |
maxLevel optional | number | undefined | |
visibleOnly optional | boolean | undefined | Only the ones the client is showing. On unless turned off. |
aliveOnly optional | boolean | undefined | Only the ones neither dead nor dying (getIsDead, isDying). |
vulnerableOnly optional | boolean | undefined | Only the ones a hit lands on now (isVulnerable). |
attackableBy optional | "melee" | "ranged" | undefined | Only the ones that weapon may hurt (_attackable: 1 melee, 2 ranged, 3 either). |
chasingOnly optional | boolean | undefined | Only the ones after a player now (SEEKTYPE_PLAYER). |
from optional | Point | undefined | Where to measure from; the player's hit point when left out. |
within optional | number | undefined | Only the ones within this many pixels of from, measured to aimAt. |
reachable optional | boolean | undefined | Only the ones there is a walk to by the room's grid; fills pathDistance. Needs navigation. |
sort optional | "distance" | "path" | "level" | "health" | "id" | undefined | distance (the default), path (on foot; needs navigation), level, health or id. |
descending optional | boolean | undefined | |
limit optional | number | undefined | At most this many, after the sort. |
AdventureActorKind
An actor's type in the words the client's own script uses (QUEST_ACTOR_TYPE_*).
type AdventureActorKind = | 'attacker'
| 'bouncer'
| 'camera'
| 'circleClocker'
| 'circleTrigger'
| 'destructible'
| 'droppedTreasure'
| 'factory'
| 'groupItem'
| 'gui'
| 'item'
| 'lightBeam'
| 'npc'
| 'placedTreasure'
| 'plant'
| 'platform'
| 'spawn'
| 'speaker'
| 'tile'
| 'timer'
| 'variable'
| 'volumeBlocker'
| 'volumeFallingPhantom'
| 'volumeHealth'
| 'volumeInteraction'
| 'volumePlacement'
| 'volumeTrigger'FoundActor
An actor a search found: what it is, where, how it stands, and its definition, in one reading.
type FoundActor = AdventureActor & {
/** Its name in the player's language, from its definition; null for an actor without one. */
name: string | null;
dead: boolean;
dying: boolean;
vulnerable: boolean;
runsAway: boolean;
/** 1 melee, 2 ranged, 3 either, 0 not at all (`_attackable`). */
attackable: number;
/** `SEEKTYPE_*`: 0 resting, 1 its path, 2 after a player, 3 after a plant (`_seekActive`). */
seeking: number;
/** How wide it is for a collision, and the circles a click, swing and touch reach to. */
radius: number;
reach: number;
touch: number;
/** How near the player must come for it to notice them, and for its icon to show. */
notice: { inner: number; outer: number };
/** The client's own answer to whether the player is inside the inner radius (`_inRadius`). */
noticed: boolean;
/** Whether it can get to the player (`pathToPlayerInRange`). */
canReachPlayer: boolean;
/** Where to aim at it: its place plus `actorOffset`; null when it could not be placed. */
aimAt: Point | null;
/** Straight-line pixels from where the search measured to `aimAt`. */
distance: number | null;
/** Pixels on foot, filled when the query asks for `reachable` or `sort: 'path'`. */
pathDistance: number | null;
npc: AdventureNpcDefinition | null;
}ActorDetail
The whole of what the client has on one actor: its row, its fighting state, its own working (QuestActor's private fields), the NPC view it is drawn with, its notice radii, and the room path it walks.
type ActorDetail = AdventureActor & {
/** The state the script has it in (`QuestManager.getQuestActorState`), or -1. */
scriptState: number;
dead: boolean;
dying: boolean;
vulnerable: boolean;
runsAway: boolean;
attackable: number;
seeking: number;
/** How fast it walks, in pixels a second, negative backing away (`_seekVelocity`). */
speed: number | null;
/** The speed the adventure gave it (`_setSeekVelocity`); 0 where it said nothing. */
setSpeed: number;
priority: number;
/** The player's distance to it, by the client (`distanceSqToPlayer`); null when unplaced. */
distance: number | null;
canReachPlayer: boolean;
reach: ActorReach | null;
notice: { inner: number; outer: number; inside: boolean };
internals: {
loaded: boolean;
prizeAmount: number;
hotSpot: boolean;
alerted: boolean;
inSeekRadius: boolean;
offScreen: boolean;
iconShowing: boolean;
torchLit: boolean;
torchInDarkness: boolean;
inCollision: boolean;
radiusOverride: boolean;
owesPosition: boolean;
seekingPlayer: boolean;
targetRange: { min: number; max: number };
directionOverride: Point;
spawnedFrom: Point | null;
lastSwingId: number;
attacking: { userId: number; weaponDefId: number; color: number } | null;
seekingActorId: string | null;
beamInFront: boolean;
eyeInFront: boolean;
};
/** The NPC view it is drawn with (`_npc`): its animation state and swing readiness. */
view: {
/** …DangerOptions
What danger counts.
| Field | Type | |
|---|---|---|
from optional | Point | undefined | Where to look from; the player's hit point when left out. |
radius optional | number | undefined | How far to look, in pixels: 600 by default. |
kinds optional | readonly AdventureActorKind[] | undefined | The kinds to count: attacker and destructible by default. |
harmless optional | boolean | undefined | Count the ones touching would not hurt (npcDef.damageTouch of 0). |
AdventureDanger
One thing near the player that can hurt them, with how much ground it watches.
| Field | Type | |
|---|---|---|
actor | FoundActor | |
noticeAt | number | Where it starts coming for the player and where it gives up: its inner and outer notice radii plus one avatar (QuestActor.onAttackRadius). |
losesAt | number | |
chasing | boolean | Whether it is after a player now. |
hidden | boolean | Whether the player stands in a stealth volume, where nothing notices them. |
slack | number | null | Pixels between the player and noticeAt; negative when already inside it. |
clear | boolean | Hidden, or outside what it watches and not chasing. |
AdventureContents
What is standing in the room now, sorted by what each thing is.
| Field | Type | |
|---|---|---|
treasure | AdventureActor[] | Chests and dropped treasure still to open. |
items | AdventureActor[] | Items still to pick up. |
crystals | CrystalActor[] | The crystals, each with the goal colour it fills. |
fighters | AdventureActor[] | Phantoms and anything else that fights. |
npcs | AdventureActor[] | The people to talk to. |
plants | AdventureActor[] | |
byKind | Partial<Record<AdventureActorKind, AdventureActor[]>> | Every actor by the client's word for its kind; kinds with none are left out. |
CrystalActor
A crystal the room holds, with the goal colour it fills.
type CrystalActor = AdventureActor & { colour: CrystalColour | null }AdventureVolume
One of an adventure's volumes: a place that does something while the player stands in it.
| Field | Type | |
|---|---|---|
actorId | string | |
kind | "volumeBlocker" | "volumeFallingPhantom" | "volumeHealth" | "volumeInteraction" | "volumePlacement" | "volumeTrigger" | |
position | Point | null | |
progress | number | null | 0 to 100 as the server last said; null until it said anything. |
visible | boolean |
SpawnOptions
How an actor is placed with spawn.
type SpawnOptions = ActOptions & {
/** Where to put it; the script's own place for it when left out. */
position?: Point;
/** Where it came from, which the client draws it arriving from. */
from?: Point;
/** Its inner and outer notice radii; the script's own when left out. */
innerRadius?: number;
outerRadius?: number;
/** Leave it out when the player already picked it up, as the room's own scene does. */
skipIfTaken?: boolean;
/** The scene's extra parameters for it. */
parameters?: string;
}ActorFollowed
One reading of an actor being followed, read in one frame of the game.
| Field | Type | |
|---|---|---|
actorId | string | |
position | Point | Where its display object stands. |
at | Point | Where to aim: position plus actorOffset. |
radius | number | |
click | number | How close a click has to be made from, and how close counts as touching it. |
touch | number | |
player | Point | null | The player's hit point in the same frame; null when it could not be read. |
distance | number | null | |
inReach | boolean | |
touching | boolean | |
seek | "player" | "still" | "patrolling" | "actor" | null | What it is doing (_seekActive): still, its path, after the player, after another actor. |
speed | number | null | How fast it walks, in pixels a second (_seekVelocity); negative backing away. |
velocity | Point | null | Which way it is going and how fast, in pixels a second: the client's speed pointed at where it is walking to (_targetX, _targetY), or along its last movement; null at rest. |
lead | Point | null | Where to walk to meet it rather than follow it; at for something standing still. |
dying | boolean | |
healthPercent | number | null | |
gone | boolean | The client took it out of the room (no parent, or no longer in _questActorsDict). |
FollowOptions
How a follow reads the client.
| Field | Type | |
|---|---|---|
everyFrames optional | number | undefined | How often, in frames; every third by default. A resting actor costs nothing either way. |
ActorFollow
A follow under way: stop it, or read its latest reading.
type ActorFollow = Running<{ latest(): ActorFollowed | null }>Motion
Something moving, for working out where to meet it.
| Field | Type | |
|---|---|---|
at | Point | Where it is now, in the avatar's coordinates. |
velocity | Point | How fast it is going along each axis, in pixels a second; zero for something standing still. |
ActorsAt
One reading of the whole room.
| Field | Type | |
|---|---|---|
actors | ActorAt[] | |
player | Point | null | |
total | number | How many actors the client's list held. |
rosterChanged | boolean | The list changed (an actor spawned, collected or removed) to bring this reading about. |
ActorAt
One actor as a watch of the room last read it.
| Field | Type | |
|---|---|---|
slot | number | |
actorId | string | |
type | number | null | |
defId | number | null | |
position | Point | null | |
distance | number | null | Pixels from the player's hit point; null when either could not be placed. |
Running
What anything long-running gives back (an auto-play, a painter, a watch kept on the wall): a handle that is itself the function that stops it, with stop under its own name too, and whatever else the thing has to say (onProgress, done). Every area's long-running act returns one of these.
const answering = await phantom.aj.adventures.dialogue.autoAccept();
await answering();
await answering.stop();Stopping twice is stopping once.
type Running<Extra extends object = object> = (() => Promise<void>) & {
stop(): Promise<void>;
/** Whether it has been stopped, by the caller or by itself. */
readonly stopped: boolean;
} & ExtraActorChange
Something the server said about an actor, as it said it.
type ActorChange = | {
/** It appeared mid-adventure, spawned by another (`qspn`): dropped treasure, a phantom. */
kind: 'spawned';
actorId: string;
type: number;
defId: number;
spawnedFrom: string;
/** What dropped treasure holds; null for anything else. */
prize: AdventureActorPrize | null;
}
| {
/** The server moved it (`qau`). */
kind: 'moved';
actorId: string;
position: Point;
velocity: number;
/** 0 nothing, 1 its path, 2 a player, 3 a plant. */
seekType: number;
/** The offset to the nearest player. */
nearest: Point;
}
| {
/** It was hit, or missed (`qahs`). */
kind: 'health';
actorId: string;
/** Its health as a percentage; null for a miss. */
healthPercent: number | null;
missed: boolean;
damage: number | null;
fierce: boolean;
}
| {
/** It was defeated or used up (`qad`). */
kind: 'died';
actorId: string;
/** Where it was put first, when the server moved it. */
position: Point | null;
/** An actor put in its place (what it dropped, say), or null. */
replacedBy: string | null;
}
| { kind: 'restored'; actorId: string; healthPercent: number }
| {
/** The script set its state (`qcmd` 1), or a variable's (`qcmdVT`). */
kind: 'state';
actorId: string;
state: number;
visible: boolean | null;
requireClick: boolean | null;
…ScriptCommand
A command the adventure's script gave the client (qcmd), other than setting an actor's state.
| Field | Type | |
|---|---|---|
command | number | A QUEST_COMMAND: 2 say, 3 ask, 4 game, 7 take item, 19 exit, 38 notify. |
args | string[] | Its arguments, as they came. |
ActorApproach
An actor crossing into, or back out of, the ground it watches around the player.
| Field | Type | |
|---|---|---|
actorId | string | |
inside | boolean | True when it came inside its notice radius of the player, false when it left it. |
distance | number | Pixels from the player's hit point to where the server put it. |
radius | number | Its inner notice radius plus one avatar, where onAttackRadius has it start coming. |
position | Point | |
at | number |
AdventureWeapon
The weapon the client fights with (QuestManager.getPlayerActiveWeapon).
| Field | Type | |
|---|---|---|
defId | number | 123, the claws, when nothing melee is worn; 0 when nothing ranged is, and nothing launches. |
color | number | |
ranged | boolean |
AdventureExperience
The player's adventure experience, as the client keeps it on their AvatarInfo.
| Field | Type | |
|---|---|---|
xp | number | |
level | number | |
levelProgress | number |
AdventureCombatStats
The player's own attack and defence range (qusu), as the client writes it onto AvatarInfo.
| Field | Type | |
|---|---|---|
attackBase | number | |
attackMax | number | |
defenseBase | number | |
defenseMax | number |
AdventureTargeting
Which phantoms count as targets, as the client's own targeting decides it.
| Field | Type | |
|---|---|---|
maxLevel optional | number | undefined | No higher level than this; every level by default. |
resting optional | boolean | undefined | Count the ones that have not noticed anybody yet. |
allies optional | boolean | undefined | Count factories and destructibles too. |
vulnerableOnly optional | boolean | undefined | Only ones that can be hurt right now. On unless turned off. |