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.
