Latest revision as of 13:20, 29 May 2021

Main Page: API:Script Index

[edit] Overview

Make awarding XP simple.

EasyExperience stores XP awards in a script-created character sheet, which allows you to easily keep track of how much XP your players have earned throughout a session. At the end of the session awarding all that XP is as easy as typing !xp session. You can also award XP directly to a specific character or group of characters for those moments when one player/character has distinguished themselves.

The script will also automatically send alerts when players level up, based on what you set the XP thresholds at. The script comes with preloaded settings for all official Pathfinder progressions (slow, medium, fast, and PFS), as well as the standard D&D 5e progression. If you use a different progression, simply edit the threshold values stored in the ExperienceThresholds character sheet generated by the script to suit your needs.

[edit] Using the Script

PC vs. NPC: The script determines if a character is a PC or an NPC based on whether or not it is controlled by a specific player. Characters with no control, or only controlled by All, are ignored.

[edit] Commands

​The API command to trigger the script is !xp. Use !xp followed by one of these commands to call the script:

• help — Shows this help menu.

• challenge — Adds an XP amount to the session tally. This can be a typed-in number (positive or negative), 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 to add that NPC's XP value 5 times). 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 XP total for the session by the number of PCs, and applies that XP to all PCs.

• config — Prompts you to select your experience progression system. Pathfinder slow, medium, fast, and society play, and D&D 5e progressions are built-in options; you may also create a custom progression system by selecting the number of levels and the starting level, and manually entering the XP thresholds in the ExperienceThresholds character sheet generated by the script. You can also set PCs to active or inactive for XP awards.

[edit] Example Macro

All-in-one macro, for use with DnD5e Shaped Character Sheet:

/w gm &{template:5e-shaped} {{title= Easy Experience}} {{content= 
Selected Token
[Token](!xp challenge 	@{selected|xp} ?{How many|1} )

Manual
[Manual](!xp challenge ?{How much|0} )  

End of Session
[Session](!xp session)  
}}

If you don't use the DnD5e Shaped Character Sheet, change the contents of the template parameter to default, and change the name of the title parameter to name.

All-in-one macro, for use with any other sheet:

/w gm &{template:default} {{name= Easy Experience}} {{content= 
Selected Token
[Token](!xp challenge 	@{selected|xp} ?{How many|1} )

Manual
[Manual](!xp challenge ?{How much|0} )  

End of Session
[Session](!xp session)  
}}

[edit] Changelog

Version 1.11521693362:

Bug Fix - Characters with no experience attribute (e.g. newly created characters) no longer cause an incorrect error message to be displayed.

Version 1.11518023682:

Bug Fix - The "over leveled" bug should now be fixed

Version 1.11:

Bug Fix - Fixed a bad variable definition that was wiping all saved settings from the state whenever the script was updated. There shouldn't be any changes to functionality with this update.

Version 1.1:

New Features

• The script no longer requires a player-name attribute. PCs are solely determined based on whether they are controlled by at least one specific player. Characters not controlled by any player or controlled only by "All Players" are ignored. You can specify what characters to add XP to in the config menu. Simply set player controlled NPC's and pets to 'MIA'
• There is now support for custom experience thresholds and for more/less than 20 levels of thresholds. This may be the cause of the error reported further down the thread; waiting on more information to figure that out.

Bug Fixes

• The script now has better handling for created, but unpopulated experience attributes
• Deleting a character that was stored in the script's memory no longer causes an API crash

Version 1.04:

Actual fix for the state corruption is put in along with logic that will hopefully automatically clean it up when it happens.

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 D&D 5E by Roll20 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.