Revision as of 23:20, 8 July 2016

Overview

Make awarding XP simple.

The script is currently in the merge queue. The code for it can be found on this branch of the Roll20 API repository.

Using the Script

PC vs. NPC:The script determines if a character is a PC or an NPC based on the value of the character's player-name attribute. If the attribute is empty, it is an NPC. If it has any value, it is a PC.

Commands

​The api command to trigger the script is !xp. The commands that can be passed with !xp are:

• help — Shows the Help screen
• challenge — Add an XP amount to the session tally. This can be a typed in number or passed via @{target/selected|npc-xp}. You can also follow this amount with the number of times you would like it added. e.g. !xp challenge @{target|npc-xp} 5. If you would like this xp to only be awarded to a specific character(s); simply add the character(s)'s ids to the end. In this case you must specify a multiplication value. e.g. !xp challenge @{target|npc-xp} 1 @{character1|character_id}} @{character1|character_id}...
• session — Divides the Session xp total by the number of PCs and applies that xp to all PCs.
• config — Select your Pathfinder experience progression (fast, medium, slow). If you use a different progression, enter the level threshold values into the ExperienceThresholds character sheet. You can also set PCs to active or inactive for xp awards.
• reset — Clears the state. Useful for fixing a corruption of the state that has been reported a couple of times and caused the script to crash the API.

Changelog

Version 1.03: Added !xp reset.

Version 1.01: Numerous bug fixes that appeared when loaded into a new game. Also added the ability to set what your sheet's experience attribute is called.

Version 1.0: Can now directly add xp to a specific character(s). Can now set what experience progression the script uses. options are Pathfinder: slow, medium, fast, and pfs; and D&D5e.

Version 0.0.5: Discovered a problem with !xp session. This has now been fixed.

Version 0.0.4: Fixed the error that was being thrown by undefined experience|max values. If the script can't handle your experience attribute for some reason, it should generate an error message in a gm whisper instead of crashing the API. You can now specify how many times to record an entered xp amount. No more having to click the macro 15 times for that big fight where a bunch of mooks were knocked about, now you just enter !xp challenge @{target/selected|token_id} 15 or !xp miscXP 200 15 if it was some sort of challenge that you don't have a npc-xp value for. The script should now generate gm whispers when xp is recorded in Session XP. There is also a global chat message when !xp session is triggered notifying all players of their xp gains in addition to any level up notices they may have received.

Version 0.0.2: Fixed an issue where if a character's level was changed from a positive value (1+) to 0, the script would throw a Reference Error and shut down all scripts. The gist in the link is updated. Can't replicate issues with 5e OGL sheet. Please let me know if they are still occuring. Issue with the 5e sheet described by Loren is actually a problem with the code where it incorrectly handles experience|max being 0 or undefined. I will work on getting the script to handle this correctly (setting max to the proper value for the character's current level, but in the meantime the work-a-round is to change the character's current level back and forth to trigger the scripts built in function for handling a level change. Note about a possible TypeError: It is possible for the script to throw a TypeError if there is a PC that has never had any experience added to it. This is because the character sheets do not generate these attributes until they have some value in them. Please make sure to enter a value in the experience field of every PC (even if it is just a zero) to get the character sheet to generate the experience attribute. You only need to do this for PC's (characters with something in the player-name attribute).

Version 0.0.1: EDIT: Designed with Pathfinder sheet in mind, known issues with 5e sheet. Easy Experience Script: This script will create a character called ExperienceThresholds that it uses for most of its functionality. If there is already an ExperienceThresholds character present, it will not make one; please make sure that you do not have a self-made ExperienceThresholds character. (highly unlikely I would think ;) ) ExperienceThresholds is created with the following attributes: Session XP: current value is updated whenever a challenge is completed. The max value stores the xp earned in the previous session in case you need it for something else. 2, 3, 4,...: these attributes' current values are the thresholds at which characters level up to this level. The default values are from the Pathfinder medium progression path. If your game uses a different XP progression, simply change the values as needed; the script only looks at these values, it does not change them.