Keywords and Journal System

This page covers the keywords support and automatic journal generation features in ISDL.

Keywords System

Keywords in ISDL provide a way to define reusable game mechanics, special conditions, and documentation that can be referenced throughout your system. There are two types of keywords:

1. Custom Keywords

Custom keywords are defined in the config section of your ISDL file:

config SystemName {
    keywords {
        Stealth summary: "Move without being detected" icon: "fa-solid fa-user-ninja" color: "#4a5568"
        Advantage summary: "Roll twice and take the higher result" color: "#38a169"
        Disadvantage summary: "Roll twice and take the lower result" color: "#e53e3e"
    }
}

Parameters:

• summary: - Description text explaining the keyword
• icon: - Font Awesome icon class (optional)
• color: - Hex color code for visual theming (optional, defaults to #666666)
• label: - Alternative display name (optional, uses keyword name by default)

2. Damage Type Keywords

Damage types are automatically converted to keywords when defined in choice fields:

DamageType damageTypeChoice choices: [
    Fire {color: "#dc2626", icon: "fa-solid fa-fire", summary: "Burns targets and can spread"},
    Ice {color: "#2563eb", icon: "fa-solid fa-snowflake", summary: "Slows movement and can freeze"},
    Lightning {color: "#7c3aed", icon: "fa-solid fa-bolt"}
]

Status Effects

Status effects represent conditions that can be applied to characters:

actor Hero {
    status Burning(svg: "icons/svg/fire.svg")
    status Blessed(svg: "icons/svg/holy-symbol.svg", when: self.Faith > 5)
    status Shielded(svg: "icons/svg/shield.svg", when: self.ShieldPoints > 0)
    death status Dead(svg: "icons/svg/skull.svg", when: self.HP <= 0)
}

Parameters (inside the (...)):

• svg: - Path to the status effect icon (SVG)
• when: - Conditional expression that auto-applies the status when true

Special Status Types:

• death status Name(...) - The death keyword goes before status and marks this as the death effect (applied when the character reaches 0 health). Only one death status per actor.

Automatic Journal Generation

When a system loads in Foundry VTT, journals are automatically created to document all keywords, damage types, and status effects. This happens in the ready hook if the GM has the "Create System Journal" setting enabled.

Generated Journal Structure

1. System Folder - A blue folder named "System"
2. System Documentation Journal - Named after your system
3. Three Pages:
   • Keywords - Lists all custom keywords with descriptions
   • Damage Types - Lists all damage types with their effects
   • Status Effects - Lists all status effects with application conditions

Journal Content Features

Keywords Page

• Usage Information Box - Explains how keywords work
• Keyword Entries - Each shows:
  • Name and icon (if specified)
  • "Keyword" badge
  • Description/summary
  • Color-coded left border

Damage Types Page

• Effects Information Box - Explains damage type mechanics
• Damage Type Entries - Each shows:
  • Name and icon (if specified)
  • "Damage Type" badge
  • Description/summary
  • Color-coded styling

Status Effects Page

• Usage Information Box - Explains status effect mechanics
• Status Effect Entries - Each shows:
  • Name and icon
  • "Status Effect" or "Death Effect" badge
  • Application condition (if specified) in human-readable format
  • Special death effect notation

Localization Support

All journal text supports full localization through the JOURNAL section in language files:

"JOURNAL": {
    "System": "System",
    "Keywords": "Keywords", 
    "DamageTypes": "Damage Types",
    "StatusEffects": "Status Effects",
    "KeywordBadge": "Keyword",
    "DamageTypeBadge": "Damage Type", 
    "StatusEffectBadge": "Status Effect",
    "DeathEffectBadge": "Death Effect",
    "AppliedWhen": "Applied when:",
    "KeywordsUsageTitle": "Keyword Usage:",
    "KeywordsUsageList": {
        "GameMechanics": "Defines special rules and mechanics for your game",
        "References": "Can be referenced in text and chat cards via @keyword", 
        "Documentation": "Provide clear explanations for players and GMs"
    }
}

Condition Translation

Status effect conditions are automatically translated to human-readable text:

ISDL Code:

death status Dead(when: self.HP <= 0)

Generated Journal Text: "Applied when: HP is less than or equal to 0"

Supported Operators:

• <= → "is less than or equal to"
• >= → "is greater than or equal to"
• < → "is less than"
• > → "is greater than"
• == → "equals"
• != → "does not equal"

Integration with Chat and Text

Keywords can be referenced in various places throughout your system:

Chat Card Integration

• Keywords can be referenced with @keyword syntax
• Hovering shows tooltip with description
• Clicking opens journal to keyword entry

Visual Styling

Keywords get consistent visual treatment with:

• Color-coded borders and icons
• Standardized layout and typography
• Responsive design that works in journals
• isdl- prefixed CSS classes for customization

Best Practices

Keyword Design

1. Keep descriptions concise - One sentence explaining the mechanic
2. Use consistent iconography - Font Awesome icons work well
3. Choose meaningful colors - Match your game's theme
4. Group related keywords - Organize by mechanic type

Status Effects

1. Use descriptive conditions - Make when: clauses clear
2. Provide appropriate icons - Visual indicators help players
3. Mark death effects - Use the death tag for character death states
4. Test conditions - Ensure status effects apply correctly

Journal Organization

The automatically generated journals serve as:

• Player reference - Quick lookup of game mechanics
• GM tool - Rules clarification and consistency
• System documentation - Comprehensive rule overview
• Translation base - Consistent terminology across languages

This system ensures your ISDL game mechanics are well-documented, consistently presented, and easily accessible to all players and GMs.