Foundry VTT DnD5e Types

Comprehensive TypeScript type definitions for the DnD5e system in Foundry VTT.

Description

This package provides comprehensive TypeScript type definitions for the DnD5e system in Foundry VTT. It is designed to be used alongside the @league-of-foundry-developers/foundry-vtt-types package, which provides type definitions for the core Foundry VTT API.

The type definitions are automatically generated and updated from the official DnD5e system code, ensuring they stay in sync with the latest features and changes.

Compatible with DnD5e version 4.3.9

Installation

npm install --save-dev foundryvtt-dnd5e-types

Usage

Add the package to your tsconfig.json file:

{
  "compilerOptions": {
    "types": [
      "@league-of-foundry-developers/foundry-vtt-types",
      "foundryvtt-dnd5e-types"
    ]
  }
}

Then you can use the types in your TypeScript code:

// Example: Access a DnD5e actor
const actor = game.actors.get("actor-id") as Game["actors"]["get"] & dnd5e.documents.Actor5e;
console.log(actor.system.attributes.ac.value);

// Example: Access a DnD5e item
const item = actor.items.get("item-id") as dnd5e.documents.Item5e;
console.log(item.system.damage.parts);

// Example: Create a new DnD5e actor sheet
class MyCustomActorSheet extends dnd5e.applications.ActorSheet5eCharacter {
  static get defaultOptions() {
    return mergeObject(super.defaultOptions, {
      classes: ["dnd5e", "sheet", "actor", "character", "my-custom-sheet"],
      width: 720,
      height: 680
    });
  }
}

// Example: Use DnD5e utility functions
const abilityMod = dnd5e.utils.calculateAbilityModifier(14); // Returns 2

Structure

The type definitions are organized into the following namespaces:

dnd5e.documents

Document classes for the DnD5e system:

• Actor5e: The base actor class for DnD5e actors
• Item5e: The base item class for DnD5e items
• Token5e: The token class for DnD5e tokens
• ActiveEffect5e: The active effect class for DnD5e effects
• ChatMessage5e: The chat message class for DnD5e messages
• Combat5e: The combat class for DnD5e combats
• Combatant5e: The combatant class for DnD5e combatants
• JournalEntryPage5e: The journal entry page class for DnD5e journal entries

dnd5e.data

Data models for the DnD5e system:

• ActorData: Data models for DnD5e actors (CharacterData, NPCData, VehicleData)
• ItemData: Data models for DnD5e items (WeaponData, SpellData, etc.)

dnd5e.applications

Application classes for the DnD5e system:

• ActorSheet5e: The base actor sheet class for DnD5e actors
• ActorSheet5eCharacter: The character actor sheet class
• ActorSheet5eNPC: The NPC actor sheet class
• ActorSheet5eVehicle: The vehicle actor sheet class
• ItemSheet5e: The base item sheet class for DnD5e items
• Dialog5e: The dialog class for DnD5e dialogs

dnd5e.config

Configuration data for the DnD5e system:

• DND5EConfig: The configuration object for the DnD5e system

dnd5e.dice

Dice rolling utilities for the DnD5e system:

• d20Roll: Roll a d20 with advantage/disadvantage
• damageRoll: Roll damage
• hitDieRoll: Roll hit dice

dnd5e.utils

Utility functions for the DnD5e system:

• calculateAbilityModifier: Calculate ability modifiers
• calculateProficiencyBonus: Calculate proficiency bonus
• And many more utility functions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build

Adding New Types

If you want to add new types or improve existing ones:

1. Find the appropriate file in the src/types directory
2. Add or update the type definitions
3. Build the project to ensure there are no errors: npm run build
4. Submit a pull request

Automated Updates

This package includes a GitHub Action that automatically checks for new versions of the DnD5e system and updates the type definitions accordingly. The action runs daily and creates a pull request when a new version is detected.

You can also manually trigger the action from the Actions tab in the GitHub repository.

How it works

1. The action checks the latest version of the DnD5e system from the official repository
2. If a new version is detected, it downloads the source code
3. It analyzes the source code to identify classes, methods, properties, etc.
4. It extracts JSDoc comments and infers types from the code
5. It updates the type definitions based on the analysis
6. It creates a pull request with the changes

Manual Update Process

You can also run the update process manually:

# Download the latest DnD5e system
npm run download-dnd5e

# Analyze the DnD5e system
npm run analyze

# Update the type definitions
npm run update-types

# Fix any declaration issues
npm run fix-declarations

# Or run the entire process at once
npm run check-dnd5e

The automated updates help keep the type definitions in sync with the latest version of the DnD5e system, but manual review is still required to ensure accuracy.

Advanced Usage

Working with Actor Data

The DnD5e system uses a complex data structure for actors. Here's how to work with it:

// Access character data
const character = game.actors.get("character-id") as Game["actors"]["get"] & dnd5e.documents.Actor5e;
const characterData = character.system as dnd5e.data.CharacterData;

// Access ability scores
const strength = characterData.abilities.str.value;
const dexterity = characterData.abilities.dex.value;

// Access skills
const acrobatics = characterData.skills.acr.total;
const perception = characterData.skills.prc.passive;

Working with Item Data

Similarly, items have different data structures based on their type:

// Access weapon data
const weapon = actor.items.get("weapon-id") as dnd5e.documents.Item5e;
const weaponData = weapon.system as dnd5e.data.WeaponData;

// Access spell data
const spell = actor.items.get("spell-id") as dnd5e.documents.Item5e;
const spellData = spell.system as dnd5e.data.SpellData;

Extending DnD5e Classes

You can extend the DnD5e classes to create your own custom functionality:

class MyCustomActor extends dnd5e.documents.Actor5e {
  // Add custom methods
  calculateCustomStat() {
    return this.system.abilities.str.value + this.system.abilities.con.value;
  }
}

class MyCustomSheet extends dnd5e.applications.ActorSheet5eCharacter {
  // Override methods
  getData() {
    const data = super.getData();
    // Add custom data
    data.customData = "Custom value";
    return data;
  }
}

Troubleshooting

Type Errors

If you encounter type errors, make sure you're using the correct type assertions:

// Incorrect
const actor = game.actors.get("actor-id"); // Type is Actor

// Correct
const actor = game.actors.get("actor-id") as Game["actors"]["get"] & dnd5e.documents.Actor5e;

Missing Properties

If you encounter missing properties, it might be because:

1. The property is new in a version of DnD5e that's not yet supported
2. The property is custom added by a module
3. The property is internal and not exposed in the type definitions

You can use type assertions to work around these issues:

// Access a property that's not in the type definitions
const customValue = (actor.system as any).customProperty;

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Foundry VTT
• League of Extraordinary Foundry VTT Developers
• foundry-vtt-types
• DnD5e System