Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:EasyExperience"

From Roll20 Wiki

Jump to: navigation, search
(Commands)
m (Added example macro all in one)
 
(7 intermediate revisions by one user not shown)
Line 2: Line 2:
 
|name=EasyExperience
 
|name=EasyExperience
 
|author={{user profile|459831|Scott C.}}
 
|author={{user profile|459831|Scott C.}}
|version=1.0
+
|version=1.03
|lastmodified=2016-06-10
+
|lastmodified=2016-06-31
 
|conflicts=None}}
 
|conflicts=None}}
  
 
==Overview==
 
==Overview==
 
Make awarding XP simple.
 
Make awarding XP simple.
 +
EasyExperience stores XP awards in a script created character and 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 is currently in the merge queue. The code for it can be found on this [https://github.com/Kurohyou/roll20-api-scripts/tree/master/EasyExperience branch] of the Roll20 API repository.
+
The Script will also automatically send alerts when players level up based on what you set the 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 script created ExperienceThresholds character to suit your needs.
  
 
==Using the Script==
 
==Using the Script==
Line 16: Line 17:
 
​The api command to trigger the script is '''!xp'''. The commands that can be passed with '''!xp''' are:
 
​The api command to trigger the script is '''!xp'''. The commands that can be passed with '''!xp''' are:
 
*'''help''' — Shows the Help screen
 
*'''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.
+
*'''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}...
<br>e.g. !xp challenge @{target|npc-xp} 5
+
<br>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.
+
<br>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.
 
*'''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.
+
*'''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.
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.
 +
 
 +
===Example Macro===
 +
'''All in one (for use with 5e shaped sheet)''' -
 +
<pre>
 +
/w gm &{template:5e-shaped} {{title= Easy Experience}} {{content=
 +
Selected Token
 +
[Token](!xp challenge &#64;{selected|xp&#125; &#63;{How many|1&#125; )
 +
 
 +
Manual
 +
[Manual](!xp challenge &#63;{How much|0&#125; ) 
 +
 
 +
End of Session
 +
[Session](!xp session) 
 +
}} </pre>
 +
If you don't use the 5e shaped sheet, change "5e-shaped" in the template field to "default", also change "title" to "name"
  
 
==Changelog==
 
==Changelog==
 +
'''Version 1.03:'''
 +
Added !xp reset.
 +
 
'''Version 1.01:'''
 
'''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.
 
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.

Latest revision as of 04:47, 13 March 2017

API ScriptAuthor: Scott C.
Version: 1.03
Last Modified: 2016-06-31
Code: EasyExperience
Dependencies: None
Conflicts: None

Contents

[edit] Overview

Make awarding XP simple. EasyExperience stores XP awards in a script created character and 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 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 script created ExperienceThresholds character 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 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.

[edit] 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.

[edit] Example Macro

All in one (for use with 5e shaped 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 5e shaped sheet, change "5e-shaped" in the template field to "default", also change "title" to "name"

[edit] 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.