Basic Scripting:Public Functions

Technically, all AdventureJS functions are public functions, because AdventureJS has no private functions, but the functions listed here have been promoted specifically for authors to use. Some of these functions are uniquely for authors; some are convenient aliases to internal functions; others are slight variations on internal functions. All of them have been chosen with new authors in mind, and you will find it useful to begin here. Though you are welcome to use any functions you find in the docs, you may find things a little less intuitive if you move beyond these functions.

MyGame.$("asset name") {String} the name or id of an asset Asset object Any asset in the game world can be referenced with MyGame.$("asset name"). It takes a string and returns a matching asset from MyGame.world["asset name"]. If no asset is found, a special null asset will be returned. The results of MyGame.$("asset name") can be chained, so you can immediately call a method on the returned asset in the form of MyGame.$("asset name").sendTo("in", "asset2 name"). That's why the function returns a null asset – so that chained functions don't throw a Javascript error. A chained function called on the null asset will always return false or null. MyGame.$() works similarly to the internal method MyGame.getAsset(), with the exception that getAsset() may return a literal null value if no asset is found.
MyGame.$("asset name").$is("in", "asset name") {String} a preposition or property {String} an optional asset name or id Boolean
This is a broad utility method that houses shortcuts for accessing various properties. Some of the more focused methods that follow can be had this way. Feel free to use whichever method makes the most sense. Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
- MyGame.$("asset name").$is("in", "other asset") accepts any preposition, asking, is this asset in that aspect of that asset?
- MyGame.$("asset name").$is("behind") accepts a preposition without an asset, asking, is this asset [preposition] any asset?
- MyGame.$("asset name").$is("nested in", "other asset") nested in, specific to character classes, asking, is this asset nested in that asset? For instance, is player on trapdoor?
- MyGame.$("asset name").$is("closed") asking, is this asset closed?
- MyGame.$("asset name").$is("locked") asking, is this asset locked?
- MyGame.$("asset name").$is("plugged") asking, is this asset plugged?
- MyGame.$("asset name").$is("sealed") asking, is this asset sealed?
- MyGame.$("asset name").$is("zipped") asking, is this asset zipped?
- MyGame.$("asset name").$is("open") asking, is this asset open?
- MyGame.$("asset name").$is("unlocked") asking, is this asset unlocked?
- MyGame.$("asset name").$is("unplugged") asking, is this asset unplugged?
- MyGame.$("asset name").$is("unsealed") asking, is this asset unsealed?
- MyGame.$("asset name").$is("held", "other asset") asking, is this asset held by that asset, as in a bannister held by player?
- MyGame.$("asset name").$is("holding", "other asset") asking, is this asset holding that asset, as in player holding a rope?
- MyGame.$("asset name").$is("worn") asking, is this asset being worn?
- MyGame.$("asset name").$is("wearing", "other asset") asking, is this asset wearing the other asset?
- MyGame.$("asset name").$is("arbitrary_property") asking, does this asset have asset.is.arbitrary_property and is that property set to true? Will return false if the asset does not have the property and will not error.
MyGame.$("asset name").isWithin("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is contained anywhere inside of another, inclusive of all of the parent asset's aspects. Which is to say, this will return true if the child asset is in or under or behind or on (or any other preposition) the parent asset, even if it's nested within other assets. Note that this method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").has("asset name") {String} the name or id of an asset Boolean This is the reverse way of asking asset.isWithin("other asset"), a shortcut method to ask whether one asset has another asset inside of it, inclusive of all of the parent asset's aspects. Which is to say, this will return true if the child asset is in or under or behind or on (or any other preposition) the parent asset. Whether you use assetA.isWithin(assetB) or assetB.has(assetA) is purely a matter of preference. Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
MyGame.$("asset name").doesContain("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset contains a substance, ie: does the bucket contain water? (Though it will also return true for tangibles, ie: does the bucket contain the shovel?) While it's similar to isWithin(), it only does a shallow search that doesn't consider nested items. Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
MyGame.$("asset name").isAttached("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is specifically in the attached aspect of another aspect, ignoring nested assets. This is functionally identical to using MyGame.$("asset name").$is("attached", "other asset"). This method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").isBehind("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is specifically in the behind aspect of another aspect, ignoring nested assets. This is functionally identical to using MyGame.$("asset name").$is("behind", "other asset"). This method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").isIn("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is specifically in the in aspect of another aspect, ignoring nested assets. This is functionally identical to using MyGame.$("asset name").$is("in", "other asset"). This method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").isOn("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is specifically in the on aspect of another aspect, ignoring nested assets. This is functionally identical to using MyGame.$("asset name").$is("on", "other asset"). This method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").isUnder("asset name") {String} the name or id of an asset Boolean This is a shortcut method to ask whether one asset is specifically in the under aspect of another aspect, ignoring nested assets. This is functionally identical to using MyGame.$("asset name").$is("under", "other asset"). This method only works for assets in the Tangible class tree, and will return false for other asset classes.
MyGame.$("asset name").$didDo("verb name") {String} the name of a verb Boolean This method asks whether the specified verb has ever been successfully applied to the specified asset as a direct object. Useful for writing one-time-use logic.
MyGame.$("asset name").$didTry("verb name") {String} the name of a verb Boolean This method asks whether the specified verb has ever been attempted on the specified asset as a direct object. This will return true regardless if the verb attempt failed or succeeded.
MyGame.$("asset name").$doCount("verb name") {String} the name of a verb Int This method asks how many times the specified verb has been successfully applied to the specified asset as a direct object. Useful for writing do-on-nth-time logic.
MyGame.$("asset name").$tryCount("verb name") {String} the name of a verb Int This method asks how many times the specified verb has been attempted on the specified asset as a direct object. Useful for writing do-on-nth-time logic. The count includes both failures and successes.
MyGame.$("asset name").iDidVerb("verb name") {String} the name of a verb Boolean This method asks whether the specified verb has ever successfully used the specified asset as a indirect object. Useful for writing one-time-use logic.
MyGame.$("asset name").$iDidTry("verb name") {String} the name of a verb Boolean This method asks whether the specified verb has ever attempted to use the specified asset as a indirect object. This will return true regardless if the verb attempt failed or succeeded.
MyGame.$("asset name").$iDoCount("verb name") {String} the name of a verb Int This method asks how many times the specified verb has successfully used the specified asset as an indirect object. Useful for writing do-on-nth-time logic.
MyGame.$("asset name").$iTryCount("verb name") {String} the name of a verb Int This method asks how many times the specified verb has attempted to use the specified asset as an indirect object. Useful for writing do-on-nth-time logic. The count includes both failures and successes.
MyGame.$("asset name").sendTo("on","asset name") {String} a preposition {String} an asset name or id Boolean This method sends one asset into the specified aspect of another asset, for instance MyGame.$("sword").sendTo("in", "scabbard"). Note that this method bypasses the usual behavior that calls verb actions, so for instance if scabbard.doMoveThatToThis("sword") were set to a custom function, that function would not be called by sendTo(). If you wanted the verb action to be called, you could instead use MyGame.$("sword").moveTo("scabbard"), which is an internal function that does invoke verb actions.
MyGame.$("asset name").sendFrom("asset name") {String} an asset name or id Boolean This method moves one asset away from another asset, without specifying a new destination. For instance MyGame.$("sword").sendFrom("scabbard") would result in the sword being moved into no place, a limbo outside of the game world. Note that this method bypasses the usual behavior that calls verb actions, so for instance if scabbard.doRemoveThatFromThis("sword") were set to a custom function, that function will not be called by sendFrom. If you wanted that function to be called, you could instead use MyGame.$("sword").moveFrom("scabbard") without the $ before moveFrom, which is an internal function that does invoke verb actions.
MyGame.$("asset name").getExits() An asset object This method returns the object of the Room that the specified asset is in. Returns false if the asset has no room (which would only be the case if it was in limbo). Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
MyGame.$("asset name").getParent() An asset object This method returns the object of the asset that the specified asset is in/on/under/behind(etc). If the asset has no parent but is in a room, the room will be returned. Returns false if the asset has no parent (which would only be the case if it was in limbo). Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
MyGame.$("asset name").getContents("in") {String} a preposition, aka attached/behind/in/on/under or "all" An array of asset IDs This is a method to get the contents of an asset's aspect. Takes a preposition and returns asset.aspects[aspect].contents. Can take "all" as a param and will return the contents of all aspects. Returns false if the asset doesn't have the specified aspect. This is a shallow list that doesn't return nested assets.
MyGame.getRoom() An asset object This method returns the object of the current room asset.
MyGame.hasQuirk("verb_means_action") Boolean This method returns a boolean indicating whether the asset has the specified verb quirk.
MyGame.getQuirks() Object This method returns a list of the asset's verb quirks.

MyGame.getExits() An object This method returns the current room's exits as an object with key/value pairs corresponding to the directions of the exits / and the IDs of the exit objects. For example, a returned object might look something like this:

{
  "out": "standing_room_out",
  "north": "standing_room_north",
  "down": "standing_room_down",
  "up": "standing_room_up",
  "south": "standing_room_south",
  "east": "standing_room_east",
  "west": "standing_room_west"
}

To make use of the return you might do something like this:

let exits = MyGame.getRoom().getExits();
Object.keys(exits).forEach(key => {
  let exit = exits[key];
  let asset = MyGame.getAsset(exit);
  let msg = `You can go ${key} through the ${asset.name}. `;
  MyGame.print( msg );
});

MyGame.$("asset name").getExits() An object If the specified asset is a room, this method returns that room's exits as an object with key/value pairs corresponding to the directions of the exits / and the IDs of the exit objects. This offers a way to get the exits of rooms other than the current one. Returns null if the specified asset is not a room.
MyGame.getDirections() An array of direction names This method returns the current room's exit directions in an array. For example, a returned object might look like this:
[ "out", "north", "down", "up", "south", "east", "west" ].
MyGame.printExits() Boolean This method prints a formatted list of available exits directly to the player. For example, a printed response might look like this:
You can go out to the Playground, north to the Pool Room, down through the hole in the ground, south, east, or west.
MyGame.$("asset name").getDirections() An object If the specified asset is a room, this method returns that room's exit directions in an array. This offers a way to get the directions of rooms other than the current one. Returns null if the specified asset is not a room.
MyGame.getPlayer() An asset object This method returns the object of the current player asset.
MyGame.getPlayer().canSee("asset name") {String} the name or ID of an asset Boolean This method checks whether the player can see the specified asset. Returns false if specified asset can't be seen for any reason, including room is dark, asset is not in room, asset is hidden inside another closed asset, etc. This method only works with Tangible assets.
MyGame.getPlayer().hasKey("asset name") {String} the name or ID of an asset Boolean This method checks whether the player is carrying a key for the specified asset. Returns false if specified asset is invalid or can't be unlocked or has not key, etc. This method only works with Tangible assets.
MyGame.getPlayer().getKey("asset name") Object or null If the player is holding any keys that unlock the specified asset, this method returns an asset object for the first key found. Returns null if player is not carrying any keys for the specified asset. This method only works with Tangible assets.
MyGame.getPlayer().getKeys("asset name") Array Since it's always possible that player may be holding multiple valid keys, this method returns an array of key asset objects, if player is holding them. Returns an empty array if player is not carrying any keys for the specified asset. This method only works with Tangible assets.
MyGame.getPlayer().getInventory() This method returns the player's inventory. This gets a deep list that includes nested assets, so long as they are known.
MyGame.getPlayer().isNested() Boolean Returns whether the player is currently nested.
MyGame.getPlayer().getNest() Returns the player's nest parent, if player is nested. Nesting is a distinct form of parent / child relationship that only applies to members of the Character class tree. Characters may be simultaneously nested in an asset while still being in a room.
MyGame.getInput() Object Returns the global input object for this turn.