Event Types Reference

Events are declared in your scenario TOML as [[events]] array entries. Each event has a type that determines its property schema and how it affects the model.

Common Properties

All events share these properties:

Property	Type	Required	Default	Description
`enabled`	bool	Yes	—	Set to `false` to disable without deleting
`type`	string	Yes	—	Determines the event behavior
`label`	string	No	—	Display label on chart annotations
`year`	int	Varies	—	The year the event occurs (required for most types)

Event Types

Retire

Permanent from the specified year. Stops earned income for that person.

[[events]]
enabled = true
type = "Retire"
person = "person1"      # Required: "person1" or "person2"
year = 2038

The event year is the source of truth for retirement timing. Create this event explicitly; the legacy person-level retirement field is only a compatibility fallback.

EndOfPlan

Marks a person’s modeled plan boundary and starts survivor behavior in a couple plan from the following year. It is a planning horizon, not a life prediction.

[[events]]
enabled = true
type = "EndOfPlan"
person = "person1"
age = 90
year = 2062

SocialSecurity

Permanent from the specified year. Adds monthly Social Security income.

[[events]]
enabled = true
type = "SocialSecurity"
person = "person1"         # Required
year = 2035

The event’s year determines claiming timing. NWN resolves the monthly benefit live from [personX].social_security_benefits at the resolved age; do not add monthly_benefit to the event.

Expense

One-time cash outflow. Can be recurring.

[[events]]
enabled = true
type = "Expense"
label = "Kitchen remodel"
year = 2028
amount = -45000                    # Negative = cash outflow
funding = "cash_reserve_first"     # Optional: let expense tap cash reserve
repeat_every_years = 5             # Optional: recurrence interval
repeat_until_year = 2048           # Optional: last recurrence year
repeat_count = 3                   # Alternative to repeat_until_year
chart_first_occurrence_only = true # Optional: show only first annotation

Income

Adds income for a period (or a single year).

[[events]]
enabled = true
type = "Income"
label = "Side consulting"
year = 2027
amount = 15000                     # Positive = cash inflow
end_year = 2029                    # Optional: last year of income

BuyHome

Records a property purchase and down payment. Create a named liability separately if the purchase is financed.

[[events]]
enabled = true
type = "BuyHome"
label = "Beach house"
year = 2032
down_payment = -80000              # Cash outflow at purchase
price = 450000                     # Total purchase price
property = "Beach House"           # Optional: name for tracking

SellHome

Converts a named property to cash, net of fees and mortgage payoff.

[[events]]
enabled = true
type = "SellHome"
label = "Sell current home"
year = 2032
property = "Primary Residence"     # Required: must match BuyHome or property name
sale_fee_rate = 0.06               # Optional: realtor fees (default 6%)
liability_names = ["Home Mortgage"] # Optional: liabilities to pay off at sale
reinvest_to = "taxable"            # Optional: bucket to deposit proceeds into
reinvest_fraction = 0.5            # Optional: fraction to reinvest (rest stays cash)

NewJob

Replaces a person’s income from the specified year.

[[events]]
enabled = true
type = "NewJob"
person = "person2"
year = 2026
annual_income = 85000

CareerBreak

Zeroes a person’s earned income for a period.

[[events]]
enabled = true
type = "CareerBreak"
person = "person1"
start_year = 2030                  # First year of break
end_year = 2031                    # Last year of break (inclusive)

Education

Subtracts annual cost for a period.

[[events]]
enabled = true
type = "Education"
start_year = 2027
end_year = 2030
annual_cost = 15000

Marriage

Currently informational. Future: tax filing status change.

[[events]]
enabled = true
type = "Marriage"
year = 2027

SpendingShift

Changes baseline retirement spending from a specified year.

[[events]]
enabled = true
type = "SpendingShift"
label = "Downsize lifestyle"
year = 2040
mode = "replace"                   # Only mode currently supported
retirement_annual = 65000          # New retirement spending level
survivor_percent_of_retirement = 0.70  # New survivor %
end_year = 2050                    # Optional: revert after this year

ContributionChange

Overrides selected contribution settings for one person from a specified year. Later changes override only the fields they supply.

[[events]]
enabled = true
type = "ContributionChange"
person = "person1"
year = 2030
annual_401k_contribution_delta = 6000

Common optional fields include annual_401k_contribution, annual_ira_contribution, their _delta variants, gross_income, and percent-of-gross contribution/match settings.

Recurring Event Fields

Events that support recurrence (currently Expense and Income):

Field	What It Does
`repeat_every_years`	How many years between each repeat
`repeat_until_year`	The last year the event occurs (mutually exclusive with `repeat_count`)
`repeat_count`	Total number of occurrences (including the first)