feat: add downtime tracking to Actor

[theholocoder]

Implement the minimal downtime foundation on the Actor (PC) sheet. This includes storing the last active in-world time and computing available downtime days based on Foundry world time.

This step introduces both data storage and derived logic, while keeping the scope small and testable.

---

Scope

• Add a downtime data structure on Actor flags
• Add UI to view and set last active time
• Compute available downtime days (derived, not persisted)
• Keep implementation compatible with PF2e Actor sheets

---

Data Model

Stored on:
actor.flags.<moduleName>.downtime

{
  "lastActiveTime": number | null
}

Notes:

• lastActiveTime uses Foundry world time (in seconds)
• availableDays must NOT be stored (derived only)

---

Logic

Implement a helper function:

computeDowntimeDays(lastActiveTime: number, currentTime: number): number

Behavior:

• Returns Math.floor((currentTime - lastActiveTime) / 86400)
• If lastActiveTime is null or undefined → return 0

---

UI

Add a “Downtime” section to the Actor sheet (tab or panel, PF2e sheet).

Display

• Last Active Date (formatted if possible, raw fallback otherwise)
• Available Days (derived value)

Controls

• Button: Set as Active Now

  • Sets lastActiveTime = game.time.worldTime

• Button: Recalculate

  • Forces UI refresh (no data change)

---

Behavior

• Available Days updates when:

  • lastActiveTime changes
  • world time changes (manual refresh is acceptable for now)

---

Acceptance Criteria

• Clicking “Set as Active Now” stores current world time in flags
• Available Days is correctly computed from world time
• No stored value for availableDays (derived only)
• UI reflects updated values after interaction
• No errors if lastActiveTime is not set

---

Notes

• This is part of a new feature called "downtime"
• Keep implementation simple and isolated
• Prefer pure functions for computation
• Ensure compatibility with future extensions (activities, history, multi-actor views)

[theholocoder]

Step 2 - Add downtime activities management to Actor (activities + end date + outcome)

Description

Extend the downtime system by introducing activities that consume downtime days, along with an explicit downtime end date and activity outcomes.

This step allows:

• defining how a character spends their downtime
• marking when downtime ends (based on world time)
• tracking whether an activity succeeded or failed

No roll automation is included yet, only structure and manual input.

---

Scope

• Extend downtime data model with:

  • activities
  • downtime end time
  • activity outcome (success/failure)

• Add UI to:

  • manage activities (add/edit/delete)
  • set downtime end date

• Validate total days used vs available days

• Keep logic local to Actor

---

Data Model

Stored on:
actor.flags.<moduleName>.downtime

{
  "lastActiveTime": number | null,
  "endTime": number | null,
  "activities": [
    {
      "id": string,
      "type": string,
      "days": number,
      "notes": string,
      "status": "planned" | "completed",
      "outcome": "success" | "failure" | null
    }
  ]
}

Notes:

• endTime represents the in-world time when downtime stops (typically next session date)
• outcome is only relevant when status = "completed"
• availableDays remains derived, not stored

---

Logic

Derived values

• availableDays = computeDowntimeDays(lastActiveTime, endTime || currentTime)
• usedDays = sum(activity.days)
• remainingDays = availableDays - usedDays

---

Validation rules

• Total usedDays should not exceed availableDays

• If exceeded:

  • show warning in UI
  • do not block input (soft validation)

---

UI

Extend the “Downtime” section on Actor sheet.

---

Downtime header

Last Active Date: [value]
End Date: [value or not set]

Available Days: X

[ Set as Active Now ]
[ Set End Date to Now ]
[ Recalculate ]

---

Activities list

Activities:

- Earn Income | 5 days | planned
- Gather Info | 3 days | completed (success)

---

Controls

• Button: Add Activity

• Each activity has:

  • Edit
  • Delete

---

Add / Edit Activity form

Fields:

• Type (simple dropdown placeholder)

• Days (number input)

• Notes (optional text)

• Status:

  • planned
  • completed

• Outcome (only visible if completed):

  • success
  • failure

---

Summary display

Used: 8 / 10 days
Remaining: 2 days

If exceeded:

Used: 12 / 10 days (warning)

---

Behavior

• “Set End Date to Now” sets endTime = game.time.worldTime

• If endTime is not set:

  • fallback to current world time for calculations

• Activities update totals immediately on change

• Outcome is optional until activity is marked completed

• No automatic roll or reward calculation yet

---

Acceptance Criteria

• Can set and store endTime

• Available days correctly computed using:

  • endTime if present
  • otherwise current world time

• Can add, edit, delete activities

• Can mark activity as completed

• Can set outcome (success/failure) for completed activities

• Used/Remaining days are correctly computed

• Warning shown when exceeding available days

• No crash if fields are missing or null

---

Out of Scope

• Roll generation
• Reward calculation
• History / archival
• Global dashboard
• Director tool integration

---

Notes

• Keep activity types flexible (no PF2e enforcement yet)
• Outcome field prepares for future roll integration
• endTime will later be important for session coordination and batch processing
• UI should remain fast and minimal to edit multiple activities quickly

[theholocoder]

Step 3 - Add downtime roll generation and resolution (per activity)

Description

Extend the downtime system to support roll generation and resolution for activities. This step introduces the ability to generate rolls for each activity and store their results (including success/failure), without enforcing full PF2e rules automation.

The goal is to:

• generate rolls from activities
• send them to chat
• store the result on the activity
• update outcome based on result (manually or semi-automatically)

---

Scope

• Add roll generation per activity
• Add UI controls to trigger rolls
• Store roll results in activity data
• Allow setting outcome based on roll
• Keep system flexible (no strict PF2e enforcement yet)

---

Data Model

Extend activity structure:

{
  "id": "string",
  "type": "string",
  "days": 5,
  "notes": "",
  "status": "planned" | "completed",
  "outcome": "success" | "failure" | null,
  "roll": {
    "formula": "string",
    "result": number,
    "timestamp": number
  }
}

Notes:

• roll is optional
• formula is a string (e.g. "1d20+12")
• result is the total rolled value
• timestamp uses game.time.worldTime

---

Logic

Roll generation

• Each activity can define a roll formula

• For now:

  • either user-defined
  • or simple default mapping (optional)

Example (optional mapping):

• earnIncome → skill-based
• gatherInfo → diplomacy

---

Roll execution

• Use Foundry Roll API:

const roll = await new Roll(formula).roll({ async: true });
roll.toMessage();

---

Result handling

• Store:

  • formula
  • total result
  • timestamp

• Outcome:

  • can be set manually
  • OR inferred later (not required now)

---

UI

Extend activity row:

Earn Income | 5 days | planned
[ Roll ] [ Edit ] [ Delete ]

---

After roll

Earn Income | 5 days | completed (success)
Roll: 1d20+12 → 24

---

Activity form additions

Fields:

• Roll formula (text input)

---

Controls

• Button per activity: Roll
• Optional global button: Generate All Rolls

---

Behavior

• Clicking “Roll”:

  • executes roll
  • sends message to chat
  • stores result

• Activity can be:

  • auto-marked as completed after roll (optional)
  • or left manual

• Outcome:

  • manually editable after roll

---

Acceptance Criteria

• Can define a roll formula per activity
• Clicking “Roll” sends roll to chat
• Roll result is stored in activity data
• UI displays roll result
• Can manually set outcome after roll
• No crash if no formula is defined (show warning instead)

---

Out of Scope

• PF2e rule validation
• Automatic DC calculation
• Reward calculation
• History integration (comes next)
• Director tool integration

---

Notes

• Keep roll system flexible and system-agnostic

• Do not enforce strict mappings yet

• This step prepares for:

  • automation
  • batch rolling
  • session start resolution

• Prefer simple implementation over completeness

• Formula examples:

1d20+12
1d20+8+2
2d6+4
1d20+@abilities.int.mod

[theholocoder]

Step 4 - Add downtime finalization and history (multiple downtime periods)

Description

Introduce the ability to finalize a downtime period and archive it into history, allowing multiple downtime periods per character.

This step enables:

• closing a downtime period (immutable)
• resetting current downtime for the next cycle
• maintaining a structured history per character

---

Scope

• Add downtime history storage
• Add “Finalize Downtime” action
• Move current downtime → history
• Reset current downtime state
• Add basic history UI (read-only)

---

Data Model

Extend:

actor.flags.<moduleName>.downtime

---

Current downtime

{
  "lastActiveTime": number | null,
  "endTime": number | null,
  "activities": [...]
}

---

History

{
  "history": [
    {
      "id": "string",
      "startTime": number,
      "endTime": number,
      "activities": [
        {
          "type": "string",
          "days": number,
          "outcome": "success" | "failure" | null,
          "roll": {...}
        }
      ]
    }
  ]
}

---

Logic

Finalize downtime

Action:

[ Finalize Downtime ]

---

Behavior

When triggered:

1. Validate:

   • lastActiveTime exists
   • endTime exists

2. Create history entry:

{
  id: randomID(),
  startTime: lastActiveTime,
  endTime: endTime,
  activities: current.activities
}

3. Push to:

downtime.history

4. Reset current downtime:

{
  lastActiveTime: endTime,
  endTime: null,
  activities: []
}

---

UI

Current downtime section

Add button:

[ Finalize Downtime ]

---

History section (new)

History

▼ 12 → 22 Gozran (10 days)
  - Earn Income (5d) → success
  - Gather Info (3d) → failure

---

Behavior

• History entries are:

  • read-only
  • collapsible

---

Acceptance Criteria

• Clicking “Finalize Downtime” creates a history entry
• Activities are copied into history
• Current downtime is reset correctly
• New downtime starts from previous endTime
• History entries display correctly
• No crash if history is empty
• Cannot finalize if required data missing (show warning)

---

Out of Scope

• Editing history
• Deleting history
• Dashboard integration
• Director tool integration
• Advanced filtering

---

Notes

• History entries must be immutable after creation

• Keep structure simple (no over-normalization)

• This step is required before:

  • dashboard
  • session integration
  • long-term campaign tracking