Start Scripting:Author Functions

Author functions are special functions, or in many cases, aliases to deeper functions, that have been surfaced for the convenience of authors. Any function with a leading $ is intended, hopefully, to make your job a little easier. As an author you are welcome to use any function you find in the Adventurejs docs, but you may find it useful to begin with these. If you do get to digging into native Adventurejs functions, it's useful to note that most of these $ functions are similar to, but not necessarily identical to, native functions. So for instance, asset.$moveTo() doesn't do quite the same thing as asset.moveTo(). If you stick to the $ functions, you're good, just be aware that things may work a little differently once you're ready to go deeper.

If you're new to programming: hey, kids! You might see these methods with the leading $ and think, "Oh, it's Jquery!" But it's not Jquery. As it happens, the only non-alpha characters that Javascript accepts as the leading character in function names are $ and _ so our options were limited. In many dev environments, _ is used to indicate private functions, and we didn't want to confuse anyone. Anyhow, if for some reason you should want Jquery and Adventurejs to coexist on a page, it shouldn't cause any problems. Adventurejs uses the $ in a way that shouldn't collide with Jquery.

MyGame.$("asset name") {String} the name or id of an asset Asset object To begin with, any asset in the game world can be referenced with MyGame.$("asset name"). MyGame.$() is a method name, equivalent to MyGame.getAsset(), that takes a string and looks for a matching asset in game.world. Allows for referencing properties and methods on the found asset with MyGame.$("asset name").myMethod(). However, be aware that trying to call a method on a non-existant asset with throw a Javascript error. For example, MyGame.$("not an asset").$didDo("take") will throw Uncaught TypeError: MyGame.$(...).bar is not a function to the console.
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 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. 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", "asset name") {String} a preposition or property {String} an optional asset name or id Boolean
This method is kind of a grab bag of shortcuts for accessing various properties. 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("some_arbitrary_property") asking, does this asset have asset.is.some_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").$has("asset name") {String} the name or id of an asset Boolean This is the reverse way of asking asset.$isIn("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.$isIn(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").$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").$iDidDo("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").$moveTo("on","asset name") {String} a preposition {String} an asset name or id Boolean This method moves one asset into the specified aspect of another asset, for instance MyGame.$("sword").$moveTo("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 will not be called by $moveTo. If you wanted that function to be called, you could instead use MyGame.$("sword").moveTo("scabbard") without the $ before moveTo, which is an internal function that does invoke verb actions.
MyGame.$("asset name").$moveFrom("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").$moveFrom("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.doMoveThatFromThis("sword") were set to a custom function, that function will not be called by $moveFrom. 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").$exits() {} 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").$parent() {} 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").$get("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 (aka asset.aspects). 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.$put("asset name","in","asset name") {String} an asset name or id {String} a preposition {String} an asset name or id This method moves one asset to the specified aspect of another asset. Returns false if no such asset or no such aspect. This does effectively the same thing as $moveTo() and which one to use is purely an author's preference. Note that this method only works for assets in the Tangible class tree, and will return null for other asset classes.
MyGame.$room() {} An asset object This method returns the object of the current room asset.

MyGame.$exits() {} 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.$room().$exits();
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").$exits() {} 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.$directions() {} 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 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").$directions() {} 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.$player() {} An asset object This method returns the object of the current player asset.
MyGame.$player().$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 or can't be unlocked or has not key, etc. This method only works with Tangible assets.
MyGame.$player().$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.$player().$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.$player().$inventory() {} This method returns the player's inventory. This gets a deep list that includes nested assets, so long as they are known.
MyGame.$player().$nested() {} Boolean Returns whether the player is currently nested.
MyGame.$player().$nest() {} 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.$input() {} Object Returns the global input object for this turn.