test
This commit is contained in:
centron\schwoerer
265
.serena/memories/pf1_damage_application_system.md
Normal file
265
.serena/memories/pf1_damage_application_system.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# PF1 System Damage Application Analysis
|
||||
|
||||
## 1. WHERE `applyDamage` IS DEFINED
|
||||
|
||||
### Primary Definition
|
||||
- **File**: `c:\DEV\Foundry2\Foundry_VTT\src\foundryvtt-pathfinder1-v10.8\module\documents\actor\actor-pf.mjs`
|
||||
- **Line**: 3780 (instance method) and 3809 (static method)
|
||||
|
||||
### Instance Method
|
||||
```javascript
|
||||
// Line 3780
|
||||
async applyDamage(value, options = {}) {
|
||||
return this.constructor.applyDamage(
|
||||
value,
|
||||
foundry.utils.mergeObject(options, {
|
||||
targets: [this],
|
||||
})
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Static Method
|
||||
```javascript
|
||||
// Line 3809
|
||||
static async applyDamage(
|
||||
value = 0,
|
||||
{
|
||||
forceDialog = false,
|
||||
reductionDefault = "",
|
||||
asNonlethal = false,
|
||||
targets = null,
|
||||
critMult = 0,
|
||||
dualHeal = false,
|
||||
asWounds = false,
|
||||
instances = [],
|
||||
event,
|
||||
element,
|
||||
message = null,
|
||||
} = {}
|
||||
)
|
||||
```
|
||||
|
||||
## 2. METHOD PARAMETERS & OPTIONS STRUCTURE
|
||||
|
||||
### Method Signature
|
||||
```javascript
|
||||
static async applyDamage(value = 0, options = {})
|
||||
```
|
||||
|
||||
### Parameters
|
||||
- **value** (number): The damage amount to apply
|
||||
- Positive = damage
|
||||
- Negative = healing
|
||||
- Returns warning if 0 or not finite
|
||||
|
||||
### Options Object Structure
|
||||
```javascript
|
||||
{
|
||||
forceDialog: false, // Forces dialog even if Shift not pressed
|
||||
reductionDefault: "", // Default damage reduction value
|
||||
asNonlethal: false, // Marks damage as nonlethal
|
||||
targets: null, // Array of Token|Actor to apply damage to
|
||||
critMult: 0, // Critical multiplier (for Wounds & Vigor variant)
|
||||
dualHeal: false, // If healing, also heals nonlethal damage
|
||||
asWounds: false, // Apply to wounds directly (Wounds & Vigor variant)
|
||||
instances: [], // Individual damage instances (not currently processed)
|
||||
event, // Triggering event object
|
||||
element, // Triggering HTML element
|
||||
message: null, // ChatMessage reference (for modules)
|
||||
}
|
||||
```
|
||||
|
||||
### Return Value
|
||||
```javascript
|
||||
Promise<false|Actor[]> // False if cancelled, array of updated actors if successful
|
||||
```
|
||||
|
||||
## 3. HOW DAMAGE IS APPLIED FROM CHAT CARDS
|
||||
|
||||
### Chat Card Button Flow
|
||||
|
||||
**Template Files**:
|
||||
- `simple-damage.hbs` (line 19-20): Simple damage/healing cards
|
||||
- `attack-roll.hbs`: Attack roll cards with damage buttons
|
||||
|
||||
**Button HTML**:
|
||||
```handlebars
|
||||
<button type="button" data-action="applyDamage" data-value="{{value.total}}">Apply</button>
|
||||
<button type="button" data-action="applyDamage" data-value="{{value.half}}">Apply Half</button>
|
||||
```
|
||||
|
||||
Or inline actions:
|
||||
```handlebars
|
||||
<a class="inline-action" data-action="applyDamage" data-type="{{type}}" data-value="...">Apply</a>
|
||||
```
|
||||
|
||||
### Click Handler Chain
|
||||
|
||||
1. **Item Chat Handler** (`item-pf.mjs`, line 1637):
|
||||
```javascript
|
||||
html.on("click", ".card-buttons button, .inline-action", this._onChatCardButton.bind(this));
|
||||
```
|
||||
|
||||
2. **_onChatCardButton** (`item-pf.mjs`, line 1643):
|
||||
- Extracts button data and message
|
||||
- Checks permissions
|
||||
- Routes to `_onChatCardAction` if action is "applyDamage"
|
||||
|
||||
3. **_onChatCardAction** (`item-pf.mjs`, line 1688):
|
||||
- Extracts damage value from `button.dataset.value`
|
||||
- Gets attack data from `message.systemRolls.attacks`
|
||||
- Builds damage instances array
|
||||
- **Calls**: `pf1.documents.actor.ActorPF.applyDamage(value, options)`
|
||||
|
||||
### Extracted Data at Application Point
|
||||
|
||||
```javascript
|
||||
// From item-pf.mjs line 1723-1731
|
||||
pf1.documents.actor.ActorPF.applyDamage(value, {
|
||||
asNonlethal, // from button.dataset.tags
|
||||
event, // click event
|
||||
element: button, // button element
|
||||
message, // ChatMessage object
|
||||
isCritical, // attack type === "critical"
|
||||
critMult: isCritical ? metadata.config.critMult ?? 0 : 0,
|
||||
instances, // damage roll instances
|
||||
});
|
||||
```
|
||||
|
||||
### Alternative Entry Point: Text Enrichers
|
||||
|
||||
**File**: `text-enrichers.mjs`, line 480
|
||||
```javascript
|
||||
actor.applyDamage(value, { ...options, event, element: target });
|
||||
```
|
||||
- Used for inline damage/heal links in chat
|
||||
- Creates damage instances from formula evaluation
|
||||
|
||||
## 4. CHAT MESSAGE FLAGS STRUCTURE
|
||||
|
||||
### Message Flags
|
||||
```javascript
|
||||
message.flags.pf1.metadata = {
|
||||
action: itemActionId, // Line 36: ItemAction UUID
|
||||
item: itemId, // Line 46: ItemPF ID
|
||||
template: templateId, // Line 67: MeasuredTemplate ID
|
||||
targets: [uuid, uuid, ...], // Line 78: Target actor/token UUIDs
|
||||
rolls: { // Line 97: Rolls data
|
||||
attacks: [
|
||||
{
|
||||
damage: [ { total: 10, damageType: "slashing" } ],
|
||||
critDamage: [ { total: 20, damageType: "slashing" } ],
|
||||
}
|
||||
]
|
||||
},
|
||||
config: {
|
||||
critMult: 2, // Critical multiplier
|
||||
}
|
||||
}
|
||||
|
||||
message.flags.pf1.subject = {
|
||||
health: "damage" | "healing" // Line 152: Type of application
|
||||
}
|
||||
|
||||
message.flags.pf1.ammoRecovery = {
|
||||
[attackIndex]: {
|
||||
[ammoId]: { recovered: count }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Relevant Message Properties
|
||||
```javascript
|
||||
message.systemRolls // Chat message rolls (init'd from flags.pf1.metadata.rolls)
|
||||
message.targets // Property getter that extracts targets from flags (line 77)
|
||||
```
|
||||
|
||||
## 5. ALTERNATIVE DAMAGE APPLICATION PATHS
|
||||
|
||||
### Instance Method Wrapper
|
||||
**File**: `actor-pf.mjs`, line 3780
|
||||
```javascript
|
||||
async applyDamage(value, options = {}) {
|
||||
return this.constructor.applyDamage(value, { targets: [this], ...options });
|
||||
}
|
||||
```
|
||||
- Used to apply damage to specific actor instance
|
||||
- Automatically sets targets to self
|
||||
- All options passed through
|
||||
|
||||
### Direct Actor Update Alternative
|
||||
Not a separate method, but damage internally calls:
|
||||
```javascript
|
||||
a.update({
|
||||
"system.attributes.hp.value": newHP,
|
||||
"system.attributes.hp.nonlethal": newNL,
|
||||
"system.attributes.hp.temp": newTemp,
|
||||
// Or for Wounds & Vigor:
|
||||
"system.attributes.vigor.value": newHP,
|
||||
"system.attributes.wounds.value": newWounds,
|
||||
})
|
||||
```
|
||||
|
||||
### No Hook Integration
|
||||
- **Hooks searched**: None found in applyDamage
|
||||
- **Pre-hooks**: None (could wrap to intercept)
|
||||
- **Post-hooks**: None (could call custom hook after update)
|
||||
|
||||
## 6. KEY IMPLEMENTATION DETAILS
|
||||
|
||||
### Health System Support
|
||||
- **Normal HP Mode**: Uses `system.attributes.hp`
|
||||
- **Wounds & Vigor Mode**: Uses `system.attributes.vigor` + `system.attributes.wounds`
|
||||
- Determined by: `healthConfig.variants[actorType].useWoundsAndVigor`
|
||||
|
||||
### Damage Flow (Normal Mode)
|
||||
1. Nonlethal damage applied first
|
||||
2. Temp HP reduced before actual HP
|
||||
3. Remaining damage reduces actual HP
|
||||
4. Cannot go below 0
|
||||
|
||||
### Damage Flow (Wounds & Vigor Mode)
|
||||
1. Vigor (temp health) reduced first
|
||||
2. Wounds (permanent damage) calculated
|
||||
3. Critical multiplier applied if applicable
|
||||
4. Wounds clamped to [0, max]
|
||||
|
||||
### Dialog Display
|
||||
- Only shown if `forceDialog` is true OR Shift key pressed
|
||||
- Allows user to:
|
||||
- Select target tokens
|
||||
- Enter custom damage reduction
|
||||
- Choose damage multiplier (normal/half)
|
||||
- Apply to specific targets
|
||||
|
||||
### Permissions Check
|
||||
```javascript
|
||||
if (!a.isOwner) {
|
||||
ui.notifications.warn(`No permission for ${actor.name}`);
|
||||
continue; // Skip this actor
|
||||
}
|
||||
```
|
||||
|
||||
## 7. WRAPPING POINTS FOR INTERCEPTION
|
||||
|
||||
### Recommended Hooks to Add
|
||||
1. **Pre-damage hook**: Before `actor.update()` calls
|
||||
```javascript
|
||||
Hooks.call("pf1.preDamageApplied", actor, updateData, options)
|
||||
```
|
||||
|
||||
2. **Post-damage hook**: After all updates complete
|
||||
```javascript
|
||||
Hooks.call("pf1.damageApplied", updatedActors, options)
|
||||
```
|
||||
|
||||
### Intercept Location
|
||||
- Line 3950 in actor-pf.mjs: `promises.push(a.update(updateData))`
|
||||
- Could wrap this to modify updateData or add custom logging
|
||||
|
||||
### For Gowler's Tracking Ledger
|
||||
- **Best approach**: Add post-damage hook
|
||||
- Call `actor.getFlag("pf1", "gowlers-tracking")` to get ledger
|
||||
- Log damage with timestamp and source
|
||||
- Store in actor flags or external system
|
||||
Reference in New Issue
Block a user