Difference between revisions of "5th Edition SRD Best Practices"

From HLKitWiki
Jump to: navigation, search
(Created page with "(Fill in here)")
 
(General Issues)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
(Fill in here)
+
= Unique Id Prefix =
 +
When choosing unique ids for the things you're creating, you should include a two-letter prefix for any things from a different publisher. This helps avoid "unique id collisions" with content that users have entered themselves, because they're unlikely to have used the same prefix as a publisher does.
 +
 
 +
This prefix can be set in the editor, by going to Tools -> Set User Identifier. It should come after the "type" of the thing, so for example the id for a Kobold Press feat would start "fKP", like "fKPPowAtt" for Power Attack from Kobold Press.
 +
 
 +
Here is the current list of id prefixes for different publishers:
 +
 
 +
* FG - Frog God Games
 +
* GR - Green Ronin Publishing
 +
* HG - Hammerdog Games
 +
* KP - Kobold Press
 +
* LG - Legendary Games
 +
* RP - Rite Publishing
 +
 
 +
Make sure the unique id prefix is set correctly for every thing you submit.
 +
 
 +
= Testing =
 +
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:
 +
 
 +
*Description text should match the book, without any extra line breaks or incorrect characters
 +
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
 +
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
 +
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.
 +
 
 +
The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.
 +
 
 +
The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.
 +
 
 +
= General Issues =
 +
==Important Note==
 +
If what you are working on calls for an item that is not in the System Reference Document or from a third-party publisher we have a licence for, leave a note on the item and flag it for our attention.
 +
== What should be shown on the Specials Tab? ==
 +
;Examples
 +
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.
 +
 
 +
::I.E: This ability gives resistance to fire damage.
 +
 
 +
::Sample Abilities: Elven Weapon Training, Expertise
 +
 
 +
:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.
 +
 
 +
::I.E: This ability grants advantage on saving throws against being frightened
 +
 
 +
::Sample Abilities: Brave, Tinker
 +
 
 +
:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab
 +
 
 +
::I.E: As a bonus action, this ability grants a bonus on melee weapon damage rolls for one minute.
 +
::Sample Rage
 +
 
 +
Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).
 +
 
 +
== What should be sourced? ==
 +
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.
 +
 
 +
;The following types of things are usually sourced
 +
:Custom Special Abilities
 +
:Custom Racial Abilities
 +
:Feats
 +
:Classes
 +
:Races
 +
:Subraces
 +
:Magic Items
 +
 
 +
;The following types of things are usually '''NOT''' sourced:
 +
:Racial Specials
 +
:Generic Abilities
 +
:Class Abilities
 +
 
 +
= Creating Races =
 +
Races are among the most complex, fiddly things in the 5th Edition SRD (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.
 +
 
 +
== First Steps ==
 +
While there are many steps in creating a race, certain things are important to handle first, because they factor into many other things.
 +
:Ability modifiers
 +
:Challenge Rating/CR
 +
:Size
 +
:Number of Hit Dice (If a creature's Hit Dice are not the standard size for the race's size, these need to be set as well.)
 +
 
 +
An optional but highly recommended step is to turn on one of the "Show stat block" options on the configure hero screen. This will show you the race's stat block and make it easier to spot differences. Note that you will have to reload before any changes take effect, either the full dataset with the Quick Reload shortcut, Ctrl+R, or only the specific race using the Test Now button in the editor.
 +
 
 +
== Race Descriptions ==
 +
 
 +
If the race has a short description at the top of the page, like many monsters in the Tome of Beasts do (usually in italics), enter that short description text in the new "Description Text" field in the editor, instead of the main description text. This allows us to display it as summary text in front of the statblock.
 +
 
 +
==Equipment ==
 +
If a race is listed as wearing manufactured armor, i.e. studded leather, it should be proficient with that armor.
 +
 
 +
If a creature's weapon is identical to a normal version of a named weapon, add proficiency with that weapon to the race and give it that weapon in the stock portfolio. Otherwise build the weapon using the 'other melee/ranged natural attack.' For example, a bugbear's morningstar attack is identical to a normal morningstar. A balor's longsword does extra lightning damage, plus has an on-hit effect. It should be built as an other melee natural attack.
 +
 
 +
== Scripts on Racial Abilities ==
 +
 
 +
Racial abilities shoud perform the following test at the beginning of their script:
 +
 
 +
:~ If we're disabled, do nothing
 +
:doneif (tagis[Helper.Disable] <> 0)
 +
 
 +
This checks to see if this ability has been disabled for some reason.
 +
 
 +
== Spellcasting /Innate Spellcasting ==
 +
If a creature has the Spellcasting or Innate Spellcasting special abilities, these helper abilities will need to be bootstrapped separately from the spells the creature can cast. A custom header can be set using the rSplHead field on the race. (If a creature has '''both''' Spellcasting and Innate Spellcasting, then separate custom headers for each ability will need to be set using the CustDesc the helper abilities.) The following substitution tokens are recognized by the script that generates the spell headers:
 +
: #name# - Creature's  name. Defaults to the race name, if something else is wanted set it in the abText field on the bootstrapped helper ability.
 +
: #lev#" - Creature's caster level.
 +
: #abil# - Name of the creature's spellcasting ability.
 +
: #splstats# = The creature's spell attack and DC.
 +
: #dc# - DC of the creature's spells.
 +
: #atk# - Creature's spell attack bonus.
 +
: #class# - The class a creature with Spellcasting draws its spells from.
 +
 
 +
See the Deva for an example of a creature with Innate Spellcasting.
 +
 
 +
== Substitution Tokens ==
 +
Several substitution tokens have been set up that can be used in ability descriptions, and in on-hit effects for natural attacks.
 +
: #StandardDC# - Substitutes the value of the abDC field.
 +
: #abSave# - Substitutes the names of any abSave tags present.
 +
: #PassiveDC# - Substitutes a passive DC value, where the passive value of a skill is used. For example, when used in conjunction with the PassiveDC.skStealth will insert the creature's passive DC value. Most often this is used for grapple DCs, which is usually the higher of the passive Strength (Athletics) or Dexterity (Acrobatics) values.
 +
 
 +
= Class Abilities =
 +
Scripts on class abilities should use the following two tests in their scripts:
 +
:doneif (tagis[Helper.ShowSpec] = 0)
 +
:doneif (tagis[Helper.Disable] <> 0)
 +
These two tests check to see if the character has reached the correct level to gain that ability and make sure the ability has not been disabled. Please note that class ability scripts should not be run before the Post-Level phase - the preferred timing is Post-Level phase with a priority of 10000. Sometimes class abilities may need to run at earlier timings, but this is very rare.

Latest revision as of 09:36, 14 March 2019

Unique Id Prefix

When choosing unique ids for the things you're creating, you should include a two-letter prefix for any things from a different publisher. This helps avoid "unique id collisions" with content that users have entered themselves, because they're unlikely to have used the same prefix as a publisher does.

This prefix can be set in the editor, by going to Tools -> Set User Identifier. It should come after the "type" of the thing, so for example the id for a Kobold Press feat would start "fKP", like "fKPPowAtt" for Power Attack from Kobold Press.

Here is the current list of id prefixes for different publishers:

  • FG - Frog God Games
  • GR - Green Ronin Publishing
  • HG - Hammerdog Games
  • KP - Kobold Press
  • LG - Legendary Games
  • RP - Rite Publishing

Make sure the unique id prefix is set correctly for every thing you submit.

Testing

It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

  • Description text should match the book, without any extra line breaks or incorrect characters
  • Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
  • No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
  • Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

General Issues

Important Note

If what you are working on calls for an item that is not in the System Reference Document or from a third-party publisher we have a licence for, leave a note on the item and flag it for our attention.

What should be shown on the Specials Tab?

Examples
Case 1 If the ability has a constant, calculated bonus only then it is not shown on the specials tab or character sheet because its effects are already accounted for.
I.E: This ability gives resistance to fire damage.
Sample Abilities: Elven Weapon Training, Expertise
Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.
I.E: This ability grants advantage on saving throws against being frightened
Sample Abilities: Brave, Tinker
Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab
I.E: As a bonus action, this ability grants a bonus on melee weapon damage rolls for one minute.
Sample Rage

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

What should be sourced?

Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should NOT have a source.

The following types of things are usually sourced
Custom Special Abilities
Custom Racial Abilities
Feats
Classes
Races
Subraces
Magic Items
The following types of things are usually NOT sourced
Racial Specials
Generic Abilities
Class Abilities

Creating Races

Races are among the most complex, fiddly things in the 5th Edition SRD (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

First Steps

While there are many steps in creating a race, certain things are important to handle first, because they factor into many other things.

Ability modifiers
Challenge Rating/CR
Size
Number of Hit Dice (If a creature's Hit Dice are not the standard size for the race's size, these need to be set as well.)

An optional but highly recommended step is to turn on one of the "Show stat block" options on the configure hero screen. This will show you the race's stat block and make it easier to spot differences. Note that you will have to reload before any changes take effect, either the full dataset with the Quick Reload shortcut, Ctrl+R, or only the specific race using the Test Now button in the editor.

Race Descriptions

If the race has a short description at the top of the page, like many monsters in the Tome of Beasts do (usually in italics), enter that short description text in the new "Description Text" field in the editor, instead of the main description text. This allows us to display it as summary text in front of the statblock.

Equipment

If a race is listed as wearing manufactured armor, i.e. studded leather, it should be proficient with that armor.

If a creature's weapon is identical to a normal version of a named weapon, add proficiency with that weapon to the race and give it that weapon in the stock portfolio. Otherwise build the weapon using the 'other melee/ranged natural attack.' For example, a bugbear's morningstar attack is identical to a normal morningstar. A balor's longsword does extra lightning damage, plus has an on-hit effect. It should be built as an other melee natural attack.

Scripts on Racial Abilities

Racial abilities shoud perform the following test at the beginning of their script:

~ If we're disabled, do nothing
doneif (tagis[Helper.Disable] <> 0)

This checks to see if this ability has been disabled for some reason.

Spellcasting /Innate Spellcasting

If a creature has the Spellcasting or Innate Spellcasting special abilities, these helper abilities will need to be bootstrapped separately from the spells the creature can cast. A custom header can be set using the rSplHead field on the race. (If a creature has both Spellcasting and Innate Spellcasting, then separate custom headers for each ability will need to be set using the CustDesc the helper abilities.) The following substitution tokens are recognized by the script that generates the spell headers:

#name# - Creature's name. Defaults to the race name, if something else is wanted set it in the abText field on the bootstrapped helper ability.
#lev#" - Creature's caster level.
#abil# - Name of the creature's spellcasting ability.
#splstats# = The creature's spell attack and DC.
#dc# - DC of the creature's spells.
#atk# - Creature's spell attack bonus.
#class# - The class a creature with Spellcasting draws its spells from.

See the Deva for an example of a creature with Innate Spellcasting.

Substitution Tokens

Several substitution tokens have been set up that can be used in ability descriptions, and in on-hit effects for natural attacks.

#StandardDC# - Substitutes the value of the abDC field.
#abSave# - Substitutes the names of any abSave tags present.
#PassiveDC# - Substitutes a passive DC value, where the passive value of a skill is used. For example, when used in conjunction with the PassiveDC.skStealth will insert the creature's passive DC value. Most often this is used for grapple DCs, which is usually the higher of the passive Strength (Athletics) or Dexterity (Acrobatics) values.

Class Abilities

Scripts on class abilities should use the following two tests in their scripts:

doneif (tagis[Helper.ShowSpec] = 0)
doneif (tagis[Helper.Disable] <> 0)

These two tests check to see if the character has reached the correct level to gain that ability and make sure the ability has not been disabled. Please note that class ability scripts should not be run before the Post-Level phase - the preferred timing is Post-Level phase with a priority of 10000. Sometimes class abilities may need to run at earlier timings, but this is very rare.