Public Functions:Get Asset Function

The get asset function, aka game.$(), is a special method that will return any game asset, tangible or intangible. The result is chainable, meaning that you can get an asset and then immediately call a function on it, which means you can do things like MyGame.$("treasure chest").getContents(). The benefit of this is that authors don't have to save references to assets, and can get them at any time.

TMI game.$() vs asset references

We offer game.$() so that you don't have to save asset references. However, you can save references if you like. Here is an example of saving a reference to an asset as it is created.

var lantern = MyGame.createAsset({ class: "Lantern", name: "brass lantern"});

// what room is the brass lantern in?
lantern.getRoom();

In this example, the variable lantern becomes globally available and can be referred to from any other script. By contrast, here's an example that uses the get asset function.

MyGame.createAsset({ class: "Lantern", name: "brass lantern"});

// what room is the brass lantern in?
MyGame.$("brass lantern").getRoom();

The results are the same. So what's the benefit of using the get asset function vs making your own reference? Well, there are several.

$() helps maintain consistency. Notice how we used a shortcut name for the reference we created? lantern vs the asset's actual name of brass lantern. That's because as humans, we're always tempted to shorten things, and it's a choice, not an error, but now let's say you have several lanterns in your game and you've forgotten which asset you assigned to which variable. Using the asset's actual name will always give you a clean identifier.
$() keeps the global namespace clean. Using the get asset function protects against "polluting the global namespace", as some developers would say. What that means is that your global variables get written to the global namespace, where they float around in one big pond together with all of the web browser's built-in functions, which can get very messy; and because global variables never get garbage collected, which means that they continue to take up memory even if they're not needed. We're not going to delve any more deeply into it here, but we invite you to look it up for further reference, if you're so inclined.
$() protects against Javascript errors. If your asset is ever destroyed, your global reference to it will return undefined, meaning that if you call a method on it, that will throw a Javascript error. But, the get asset function will return a special null asset that has most of the common asset functions, and will not throw an error.

The bottom line is: if you're new to Javascript development, you're probably safer using $(). If you're an experienced developer and you feel comfortable managing your own references in the global namespace, go for it.

MyGame.$("asset") {String} asset a name or id representing an asset Object Any asset in the game world can be referenced with MyGame.$("asset"), where "asset" is the name or ID of a game asset. $() takes a string and returns a game asset. The results of MyGame.$("asset") can be chained, meaning that you can immediately call a function on the returned asset, for example: MyGame.$("asset").to("in", "asset2"). If no asset is found, a special null asset will be returned to prevent Javascript errors. A chained function called on the null asset will always return false or null.
Expand for example
```
MyGame.createAsset({ class: "Lantern", name: "brass lantern"});

// is the brass lantern in the crystal cave?
if( MyGame.$("brass lantern").getRoom() === "crystal cave" ) {
  // do something
};
```

TMI game.$() vs game.getAsset()

If you go looking through the AdventureJS code, you'll find frequent uses of game.getAsset(). The methods game.getAsset() and game.() are very similar but have important distinctions. Chief among them is that when game.getAsset() fails to find an asset, it returns null, but when game.$() fails to find an asset, it returns a special asset of class Null. The Null asset exists specifically to catch chained author queries such as MyGame.$("foo").to("bar") without throwing a Javascript error.