Advertisement Create a free account

API Updates - 3/27/2018

1522169594

Edited 1522257189
Steve K.
Roll20 Team
The "imgsrc" property The "imgsrc" property on objects got a tweak. Previously any object that had an "imgsrc" or "avatar" property but was not given a url at creation threw an error. Now many of these objects can accept an empty string and allows these objects to be created without an error if these attributes are left blank or not included. Global Variable "defaults" defaults = {sheet: {}, game: {}}; This object contains the saved defaults for the game. defaults.game contains settings for the game defaults.sheet contains character sheet defaults If the user has not changed any of their default settings both defaults.game and defaults.sheet will be empty objects. Changes to this object will not be saved between sessions. setAttrs setAttrs(character_id, attribute_obj, settings(optional)) This function works like the setAttrs sheet worker function, except that the first argument must be the id of the character whose attributes you are changing. The second argument must be an object containing the attributes and values you wish to change, in the format attribute_name: value. This function can be used with the defaults variable to easily create characters with the game's default settings by simply passing in defaults.sheet as the second parameter. By default, this function will trigger sheet workers, this can be disabled by passing in "{silent: true}" as a third parameter. Reset Fog resetFog( [playerids](optional), pageid(optional) ) Graphic adv_fow_view_distance (read/write) Page adv_fow_enabled (read/write) adv_fow_dim_reveals (read/write) adv_fow_show_grid (read/write) You can use this function to reset advanced fog of war. You may pass in [playerids] as an array containing the ids of the players to be reset, or as a string containing one id, or as the string "all". The function will remove invalid ids from the array, and fail with an error if no valid ids are found. If this property is completely omited, it will default to all players. You may also pass in a page id to specify which page to reset the fog on, if this is omitted it will default to the page the players are currently on. The following are all valid examples of this function: var playerObjs = findObjs({_type: "player"}); var player1 = playerObjs[0].id; var players = [playerObjs[0].id, playerObjs[1].id]; var pageid = Campaign().get("playerpageid"); resetFog(); //resets the fog for all players on the current player page resetFog(players); //resets the fog for players 1 and 2 on the current player page resetFog(player1); //resets the fog for player 1 on the current player page resetFog(players, pageid); //resets the fog for players 1 and 2 on the page with id [pageid] resetFog("all", pageid); //resets the fog for all players on the page with id [pageid] cardInfo cardInfo( { options } ) Returns information about a group of cards, or one specific card. This function accepts the following options: { type: "hand", "graphic", "discard", "play", "deck", "all", "card" //Required. Determines what kind of results are returned. deckid: deckid //Required for all types except 'card'. Determines which deck to return information about. cardid: cardid //Required for type 'card'. Determines which card to return information about. discard: true/false //Optional. Determines whether result will include cards in the discard pile. Ignored for types 'card', 'all', and 'discard'. Defaults to 'false' if omitted. } As noted above, the type will determine what results are returned. "card" returns a single object containing information about the card corresponding to cardid, with the following format: { type: "graphic", "hand", "deck", or "discard", id: The id of the graphic, hand, or deck containing the card. Omitted for type "discard", cardid: The id of the card, pageid: The id of the page containing the graphic. Omitted for other types, playerid: The id of the player holding the card. Omitted for other types, index: The position of the card in the hand or discard pile. Omitted for types "graphic" and "deck" } The other types return an array of these objects. "hand" will return info on all cards in that deck that are currently in player's hands. "graphic" returns info on the cards of that deck currently on the table. "discard" returns only the cards that are in the discard pile, and "deck" returns the cards that are still in the deck. "play" returns a combination of "hand" and "graphic", and "all" returns all cards belonging to that deck. You can also include the setting discard: true to include the cards in the discard pile in the results. This has no effect on the types "discard" and "all". If the function fails, it will return false. If no information is retrieved, it will return an empty array. recallCards recallCards(deckid, type(optional) ) Functions identically to using the 'recall' dialog on a deck. The type parameter is a string that determines which which cards are recalled, the valid types are hand, graphic, and all. If omitted, the type defaults to 'all'. Will return false if the function fails, returns true if successful. shuffleDeck shuffleDeck(deckid, discard(optional), deckOrder(optional) ) Shuffles a deck. If this is called with only the deckid passed in, it is identical to clicking the 'Shuffle' button, except any errors encounter will log to the api console instead of producing a browser alert. The second parameter allows you to specify whether or not to shuffle the discard pile back into the deck. The default is true, which shuffles the discard pile back into the deck as it would normally when clicking the shuffle button. Passing in 'false' will leave the discard pile as it is and only shuffle the remaining cards in the deck. If you call this function with an array of card ids as the second parameter, the deck will be re-shuffled and put in the order of that array. Note that the cards in this array must match the cards left in the deck exactly (plus the discard pile, if you specify discard = true), or it will fail with an error. You can use the provided cardInfo function, in combination with the _.pluck function from the underscore.js library to easily get the list of cards the function expects, like so: _.pluck(cardInfo({type: "deck", deckid: deck.id , discard: (true/false, depending) }), "cardid"). Will return false if the function fails, returns an array of card ids representing the new deck order if successful. drawCard drawCard(deckid, cardid(optional) ) Draws a card from a deck. You can pass in a card id to draw a specific card from the deck. If this is omitted, it will draw the top card.The function returns the id of the drawn card if successful, and false if it fails. pickUpCard pickUpCard(cardid, fromDiscard(optional) ) Picks up a card from the table (if fromDiscard is false or omitted), or from the discard pile (if fromDiscard is true). Note that it isn't necessary to use this function to play a card from the discard pile, as using giveCardToPlayer or playCardToTable will automatically remove the card from the discard pile if it is there. However, this function may be useful as it will return false if the card is not in the discard pile. The function returns the id of the card if successful, and false if it fails. takeCardFromPlayer takeCardFromPlayer(playerid, options(optional) ) Takes a card from the player with id playerid. If options are omitted, it will take a random card from that player's hand. You can add properties to the options to specify a card to take, "index" to specify an index of the currentHand array, or "cardid" to specify a card by id. By default, the function will remove the card from the players hand and return the id for that card. However, you can add the property "steal" to the options parameter, and give it a player's id to trigger the steal card dialog for that player. This functions identically to clicking on 'Steal Card' in another player's hand. Note that although this still returns the card id, the card will remain in a player's hand and should not be played elsewhere without being removed from the hand. Returns the id of the card if successful, and false if it fails. Note that if the 'steal' option is used, the function will return a card id, but this does not necessarily mean that the card changed hands, as that will be up to the player to approve or deny the steal request. giveCardToPlayer giveCardToPlayer(cardid, playerid) Gives a card (with id cardid) to a player (with id playerid). playCardToTable playCardToTable(cardid, settings(optional) ) Plays a card (with id cardid) to the table. The settings parameter can be used to customize the resulting token, if omitted default settings will be used. Here are the possible settings with their defaults: { left: X position in pixels. Defaults to the center of the page. top: Y position in pixels. Defaults to the center of the page. width: width of token in pixels. Defaults to the deck's defaultwidth, or to 98 if the deck has no default. height: height of token in pixels. Defaults to the deck's defaultheight, or to 140 if the deck has no default. layer: the layer the token will appear on. Defaults to the objects layer. pageid: the page the token is played to. Defaults to the current player page. isdrawing: whether to treat the token as a drawing. Uses the deck "treatasdrawing" as the default. currentSide: whether the card is played face up or face down, with 0 being face up and 1 being face down. Defaults to the deck's default setting. } dealCardsToTurn dealCardsToTurn(deckid) Deals a card from the deck to each object in the turn order. Functions identically to clicking the 'Deal cards to turn order items' in the 'Deal cards' dialog box. Note that in this case, any errors encountered (for example, if you run out of cards before you finish dealing) will produce a browser alert in the same way as if the user clicked the button themselves. A note on the use of these functions : These functions were structured so that playing a card mimics how you would do that in real life. You first must pick up a card, by taking a card from the deck, table or from another player (drawCard, pickUpCard, and takeCardFromPlayer, respectively). With the card now in hand, you can now either play it to the table (playCardToTable) or give it to a player (giveCardToPlayer). Using any of the 'take' functions will remove the card from play and return the id for that card, and also add the card to the discard pile. This is to prevent unpredictable behavior that may result from having a card completely unaccounted for. However, if you immediately use a 'play' function using the returned card id, the card will be put back in play before the discard pile is updated, so that the players will not see the card get added to the discard pile. If you wish to hold on to a card before playing it and you do not wish for it to end up in the discard pile, consider playing the card to the table on the GM layer, or perhaps to a page that the players aren't currently on. Playing a card without first using a 'take' function could lead to duplicates that may not behave as you expect. Depending on deck settings and where the duplicates are in play, the game may (or may not) remove one of the duplicates automatically. Regardless, when cards are recalled and the deck is shuffled, the game will ensure there are no duplicate cards in the deck. It's worth noting that the 'take' functions are also the best way to discard a card. You can simply call 'destroy' on a card played to the table, or manually remove a cardid from a player's currentHand, and these cards will eventually end up in the discard pile. However, it would be difficult to predict when the discard pile will be updated, and if multiple cards are removed this way, they may not wind up in the discard pile in the correct order for this reason. Using one of the 'take' functions will automatically update the discard pile each time one is called, ensuring that cards are discarded in the order they are removed.
1522170311
Stephen L.
Pro
Marketplace Creator
Sheet Author
API Scripter
Awesome! Thanks for the great work and continued support to the API!
I just logged in to run my game, but all my custom API scripts are now broken. I suspect this might be due to the update. I haven't changed anything since they last worked, but now I get this: Your scripts are currently disabled due to an error that was detected. Please make appropriate changes to your scripts and click the "Save Script" button and we'll attempt to start running them again. More info... For reference, the error message generated was: Error setting up state: SyntaxError: Unexpected end of JSON input
I believe this bug is a result of the update. https://app.roll20.net/forum/post/6223311/syntaxerror-unexpected-token
1522174467
Steve K.
Roll20 Team
We're aware of the issue and investigating.
1522178932
Steve K.
Roll20 Team
We've currently rolled back this updated, due to some users having issues loading their API sandbox. We're continuing to investigate the root issue and why some games were affected and others were not. We'll update here when we have more information. 
1522249654

Edited 1522249677
Scott C.
Pro
Sheet Author
API Scripter
Also, just wanted to note that your documentation in the OP is a little out of date since setAttrs was changed in the beta period to trigger sheetworkers unless a third argument of {silent:true} was passed. Thanks for all your (and the whole Roll20 Team) hard work Steve.
1522257134
Steve K.
Roll20 Team
Scott C. said: Also, just wanted to note that your documentation in the OP is a little out of date since setAttrs was changed in the beta period to trigger sheetworkers unless a third argument of {silent:true} was passed. Thanks for all your (and the whole Roll20 Team) hard work Steve. Updated, thanks.
1522257175
Steve K.
Roll20 Team
The API update should all be live again, with the exception of the Global Variable "defaults", which have been removed for further testing.
1522771940
Steve K.
Roll20 Team
We pushed out an update this morning that should make the Game Defaults section of this update available again. If you are experiencing any API disruptions, particularly on older games, please let us know.
1522836302

Edited 1522942649
Nibrodooh
Pro
Sheet Author
Using drawCard does not seem to account for infinite decks. Once a card is drawn it seems it is not possible to draw another copy until the deck has been shuffled.  Edit: Upon further investigation shuffling made the card available via the regular choose menu again, but the API can not obtain another copy of the card.
1523566681
Guls
Pro
Steve K. said: We pushed out an update this morning that should make the Game Defaults section of this update available again. If you are experiencing any API disruptions, particularly on older games, please let us know. I've reported the issues I'm having on this thread . In short: the WFRP3 API Script has worked for years on the game. After testing on April 5, the script didn't work at all. I deleted everything and re-entered the script on April 6th and it worked. Next game session was on April 12 (today) and once again the script doesn't work and the error message comes back. Note that there's been no modification of the script on my end before it stopped working, and the issues seems to be on the sandbox rather than on the script itself. Without this script there's no way to play Warhammer 3rd Edition on Roll20. Any chance to get some light shed on this ?
1523570399
Liam
Pro
Steve K. said: We pushed out an update this morning that should make the Game Defaults section of this update available again. If you are experiencing any API disruptions, particularly on older games, please let us know. I have an Ars Magic game I am running which has an API script provided to me by a kind fellow who was working on a script prior to there being one in the script library - this stopped working a week ago after the update. I am getting a similar error and disabling the scripts i have running and just using the script from the library also results in the same error, which is Error setting up API settings: SyntaxError: Unexpected token in JSON at position 3120 Disabling and enabling scripts just results in the position number changing - can someone have a look at this for me? I have tried deleting these scripts as well and continue to get this error.
1523671023
Scott C.
Pro
Sheet Author
API Scripter
Was the imgsrc fix not pushed? I'm still seeing these errors pop up on API triggered character creation
1523699518
Guls
Pro
Liam said: I have an Ars Magic game I am running which has an API script provided to me by a kind fellow who was working on a script prior to there being one in the script library - this stopped working a week ago after the update. I am getting a similar error and disabling the scripts i have running and just using the script from the library also results in the same error, which is Error setting up API settings: SyntaxError: Unexpected token in JSON at position 3120 Disabling and enabling scripts just results in the position number changing - can someone have a look at this for me? I have tried deleting these scripts as well and continue to get this error. Getting the same error on my Warhammer game. Never got a response from Roll20 on any question related to this for the past couple of weeks.
1523723065
keithcurtis
Roll20 Mod Team
It was working on the 6th, from your post above? This week was the staff retreat for Roll20. It could be why you haven't gotten a response by today (the 14th). Have you tried directly emailing them at team@roll20.net?
1523740657
Guls
Pro
keithcurtis said: It was working on the 6th, from your post above? This week was the staff retreat for Roll20. It could be why you haven't gotten a response by today (the 14th). Have you tried directly emailing them at team@roll20.net ? I'd been looking for some sort of Customer Support contact address but couldn't find any. Thanks, I've followed your recommendation, will update if I get any response.
1524170993
Guls
Pro
Guls said: keithcurtis said: It was working on the 6th, from your post above? This week was the staff retreat for Roll20. It could be why you haven't gotten a response by today (the 14th). Have you tried directly emailing them at team@roll20.net ? I'd been looking for some sort of Customer Support contact address but couldn't find any. Thanks, I've followed your recommendation, will update if I get any response. Happy to say that the issue seems to have been fixed !
1524968162
Scott C.
Pro
Sheet Author
API Scripter
Scott C. said: Was the imgsrc fix not pushed? I'm still seeing these errors pop up on API triggered character creation Just wanted to check in on this. Is this fix supposed to be live?
1525102423
Steve K.
Roll20 Team
Scott C. said: Scott C. said: Was the imgsrc fix not pushed? I'm still seeing these errors pop up on API triggered character creation Just wanted to check in on this. Is this fix supposed to be live? Yes this should be live and working. If it's not can you please give a detailed summary of how you're calling the create object, object type, and the error you're recieving. 
1525109764
Scott C.
Pro
Sheet Author
API Scripter
Thanks Steve, I've tried both of the following: on('ready',()=>{     createObj('character',{name:'Version Check',avatar:''}); }); on('ready',()=>{     createObj('character',{name:'Version Check'}); }); Both give a double instance of the error (probably one for the avatar and one for the default token?): "ERROR: You cannot set the imgsrc or avatar of an object unless you use an image that is in your Roll20 Library. See the API documentation for more info." "ERROR: You cannot set the imgsrc or avatar of an object unless you use an image that is in your Roll20 Library. See the API documentation for more info."
1525293756
Steve K.
Roll20 Team
Looks like this exception got merged out of the final code launch. I've put it back in and that update should go live to the API server Soon TM.
1525294452
Scott C.
Pro
Sheet Author
API Scripter
Thanks Steve
1525901747
Steve K.
Roll20 Team
This fix should be live. Please let us know if you're still having related issues.