(*- Just about whenever/wherever. Some text displays (titles, quantities, etc...) are too small to warrant making them full-fledged web views.)
So, to use ARISjs, first find the text area corresponding to when you want the script to be invoked (for example, if you want to give the player a random number of widgets when they view a plaque, go into the plaque editor). From here, enter this into the Text field:
This will be the basic shell around all ARISjs scripts. In short, it lets ARIS know to pay attention to this Web View, and gives you a chance to tell ARIS what to do after ARIS is ready to recieve commands (for a more technical account of what is going on, see the 'Technical Documentation' section).
Within the ARIS.ready block (the "your code goes here" section), you are safe to use any of the ARISjs API calls. The API is as follows:
If simply copied and pasted in place of the "// your code goes here" line, any of these calls would execute immediately upon the text popping up on screen. For example, the code:
if put in a plaque will, as soon as the plaque is opened, set the quantity of item with id 1234 to 10 (Note that "setting the qty to x" is not directly possible through native means within ARIS; the editor only offers incrementing and decrementing). Similartly, if "ARIS.setItemCount(1234,10);" was replaced with "ARIS.exit();", the plaque will close as soon as it is opened.
So, what if you want to have the script executed at some time other than immediately upon opening? Currently, ARIS supports execution on player input in a few places: Quest Descriptions and Plaques* (<- plaques coming soon).
For example, if you wanted to vibrate ARIS, give the player a penny, and exit to the map upon hitting "begin quest", you would place the following in the quest's description:
There are two ways to accomplish this: via callbacks, or via a cache.
NOTE- for the majority of simple modifications of player inventory, using the cache is sufficient, and you shouldn't need to use callbacks (feel free to skip to the 'cache' section). However, if you plan on accomplishing more advanced tasks, it is worthwhile to understand how the callback API functions.
Say you want a plaque to remove 10% of a player's dollars. Because there is no increment-or-decrement-by-percent API, we'll need to know the player's currently owned qty to derive the desired quantity, and then use the API to set that. Here is an example of what that might look like:
First thing to note is that this code is much larger and more complex than the previous examples that simply request that ARIS performs some action. The reason for this falls into a more advanced concept within programming- asynchronous communication.
Whenever ARISjs communicates with ARIS (or visa versa), there is an undetermined amount of time that will pass between the "request" and the "response" (this time is usually sub-millisecond, so don't worry about it from the perspective of player perception). Because of this, the "request" and "response" must be separated in code.
The "response" is a block of code that will get called once ARIS is done with what you've requested it, and potentially has some information ready for you. The "request" is the expression of a desire for ARIS to perform some action at its soonest convenience. The way this often works is by first defining the "response" ("hey, when you're done, you should call this block"), then sending off the "request" ("ok, so now that you know what to do when you're done, go find the qty of the player's item!").
In this case, the "response" is "ARIS.didUpdateItemQty" (every request that uses callbacks has a matching response block with a defined name). So, all you have to do is define what that block is, and then you are free to send off the request. Inside the response block, you can do whatever you want with the returned qty (the qty and item id are passed into the response block via function arguments). It is good practice to ensure the item_id in the block is the item_id you care about before performing any actions on the data, as multiple asynchronous calls might share the same response block. It is also good practice to clean up your response block attachments if you no longer intend to use them (for reasons we will see shortly...).
ARIS.getItemCount is not the only asynchronous API call. In fact, every API call is asynchronous (except ARIS.cache.getItemCount, but we'll get to that...), they just use empty response blocks as they don't care what happens when ARIS is done. This means that our previous example containing:
actually played out more like ARISjs giving ARIS a list of things to do, that "eventually" get done (in computer time, "eventually" means a millisecond later...). This is a subtle difference that you will most likely not need to worry about for simple operations. (One such difference is that even after the line "giveItemCount" has been run, the player's qty will still not yet have increased).
The API calls with callbacks are as follows:
If you notice, set, give, and take all use the same callback as get for ItemCount. You can still use any of these without defining the response block if you don't care about the response. But make sure that if you DO have a response block, you are ready to handle it being called after any of these requests. (In the above example, if we didn't detach the response block (set it to an empty function) after we got the information we needed, the ARIS.setItemCount we call within the response would result in the same response block being called again, creating an infinite loop.)
You might be asking "why would you need a response block for set, give, or take?". While none of those requests are necessarily explicitly asking for information, the response might be something other than exactly what you requested. For example, you might request to give the player 100 coins, but that would put them over the max number of coins allowed by their inventory (either by max_qty or max_inventory_weight). In this case, the response block would show that this happend (qty passed into the response block would be less than 100 + their previous qty). Or, you can use the response block as assurance that everything went as expected by comparing the newly set qty with your requested qty. Again, if this is more information than you care about, just make sure the response block isn't set and you don't have to worry about it.
Ok. So asynchronous communication is complicated. What if you just want to simply modify the qty of an inventory item based on its current value, and don't want to deal with all that complexity?
ARIS.cache was created for just this purpose.
We'll use the same example (remove 10% of a player's dollars) to illustrate the differences between the methods. Here is the example with a cache:
The most noticable difference is the great decrease in complexity and code length using this method. This requires no callbacks, no asynchronous communication, and uses the inline return value of the function.
So why not use this method? Like its name implies, this API just references a cache; it doesn't actually talk directly to ARIS. This means that any changes to the player's quantity that occur AFTER the script is initially run will NOT be reflected in the result.
For example, say you've created a large interactive that potentially doubles and halves qty of an item called "points" from a player's inventory. Every time they double points you need to know how many they currently have to determine how much to give them. If you use the cache, the first time you request their currently owned points will be correct; so you double that number and set their owned quality. Then, if they double it again, the cache will not have changed/updated and so your "doubling" their points will actually just be "doubling" their previously owned points- not what you intended to do.
So, the rule of thumb is that if you simply want to perform one operation based on the qty of an item in the player's inventory, using the cache is the simpler, more straightforward, and less error-prone option. Anything more complicated than that, and you might need to look into callbacks.
A repository of ARISjs examples are available at https://github.com/ARISGames/ARISjsExamples
ARIS Editor - Making >