# Event Categorization Notes

This document explains decisions made when categorizing events into the new folder structure.

## Events That Were Hard to Categorize

### 1. School Year Transitions (school_year/transitions.py)

**Challenge**: This file contains 17 events that span multiple categories.

**Events Included**:
- School progression: `school`, `graduate5th`, `graduate8th`, `graduate12th`
- College transitions: `college`, `collegeParty`, `collegeGreekLife`, `collegeMinor`, `collegeMissHome`
- Adult life: `adultMissFriends`
- Driver's education: `driversLessons`, `driversTest`
- Social/relationships: `positiveInteraction`, `extendedFamily`, `funeral`, `murderAttempt`
- Energy management: `lowEnergyEvents`

**Decision**: Kept together as `school_year/transitions.py`

**Reasoning**:
- These events are tightly coupled to the school calendar system
- They trigger on specific dates or school transitions
- They share common dependencies on education status
- Splitting them would create circular dependencies
- The file documents a complete "school year lifecycle"

**Alternative Considered**: Split into:
- `school_year/progression.py` - School/college transitions
- `school_year/social.py` - Social events during school
- `school_year/life_events.py` - Funerals, family, etc.

**Why Rejected**: Would spread related events across too many files and create confusion about where school-related events belong.

---

### 2. Driver's Education Events

**Events**: `driversLessons`, `driversTest`

**Current Location**: `school_year/transitions.py`

**Alternatives Considered**:
- `adolescence/milestones.py` - Age-based milestone
- `education/activities.py` - Educational activity
- `adulthood/independence.py` - Step toward independence

**Decision**: Kept in `school_year/transitions.py`

**Reasoning**:
- Typically happens during high school years
- Often scheduled through school
- Part of the teen-to-adult transition
- Already grouped with other high school events

---

### 3. Extended Family and Social Events

**Events**: `extendedFamily`, `positiveInteraction`, `funeral`, `murderAttempt`

**Current Location**: `school_year/transitions.py`

**Alternatives Considered**:
- `random/social.py` - Random social encounters
- `relationships/events.py` - Relationship-focused events
- Move to existing relationship modules

**Decision**: Kept in `school_year/transitions.py` for now

**Reasoning**:
- These were originally in `dayEvents.py` with school events
- They're often triggered during school/college years
- Moving them would require creating new relationship folders
- Can be refactored later if relationship module is expanded

**Future Recommendation**: If/when a `relationships/` folder is created, these events should move there.

---

### 4. Low Energy Events

**Event**: `lowEnergyEvents` (in school_year/transitions.py)
**Similar Event**: `lowEnergyEvent` (in health/events.py)

**Note**: These are **different events** despite similar names:
- `lowEnergyEvent`: Single message event about being exhausted
- `lowEnergyEvents`: Question event with coping mechanism choices

**Current Location**:
- `lowEnergyEvent` → `health/events.py`
- `lowEnergyEvents` → `school_year/transitions.py`

**Alternative Considered**: Both in `health/events.py`

**Decision**: Kept separate

**Reasoning**:
- Different event types (message vs. question)
- Different purposes (notification vs. choice)
- `lowEnergyEvents` has school/work-specific logic
- Keeps backward compatibility with dayEvents.py imports

**Future Recommendation**: Consider renaming for clarity:
- `lowEnergyEvent` → `lowEnergyMessage`
- `lowEnergyEvents` → `lowEnergyCopingChoices`

---

### 5. Conversation and Tutorial Systems

**Modules**: `conversationEvents.py`, `tutorial_events.py`

**Decision**: Copied wholesale to new locations
- `conversationEvents.py` → `events/conversations/npc_interactions.py`
- `tutorial_events.py` → `events/tutorial/onboarding.py`

**Reasoning**:
- These are complete, self-contained systems
- Many internal dependencies and helper functions
- High risk of breaking if split apart
- Better to keep as monolithic modules for now

**Future Recommendation**:
- **Conversations**: Could be split into:
  - `conversations/base.py` - Classes and helpers
  - `conversations/types.py` - Different conversation types
  - `conversations/ai.py` - OpenAI integration
- **Tutorial**: Could be split into:
  - `tutorial/helpers.py` - Tutorial mode detection
  - `tutorial/events.py` - Tutorial-specific events
  - `tutorial/modifiers.py` - Event modification logic

---

### 6. Negative Habit Event

**Event**: `negativeHabitEvent`

**Current Location**: `health/events.py`

**Alternative Considered**: `random/negative.py` (behavioral consequences)

**Decision**: Placed in `health/events.py`

**Reasoning**:
- Directly affects health, energy, happiness stats
- Related to health conditions and well-being
- Part of long-term health consequences
- Fits the "health and wellness" theme

---

### 7. Birthday Event

**Event**: `birthday`

**Current Location**: `holidays/annual.py`

**Alternative Considered**: Special category or life milestones

**Decision**: Placed in `holidays/annual.py`

**Reasoning**:
- Annual recurring event (like other holidays)
- Date-based trigger (player's birth date)
- Celebratory nature similar to Christmas, etc.
- Makes sense grouped with other calendar events

---

### 8. Immunizations and Vacation

**Events**: `immunizations`, `vacation`

**Current Location**: `holidays/annual.py`

**Alternative Considered**:
- `health/events.py` - For immunizations
- `childhood/activities.py` - For vacation
- `random/positive.py` - For both

**Decision**: Placed in `holidays/annual.py`

**Reasoning**:
- Both are special one-time or rare events
- Childhood-specific but not really "milestones"
- Similar random chance triggers
- Fit the theme of "special occasions"
- Originally in dayEvents.py together

---

## Cross-Cutting Concerns

Some events could logically belong to multiple categories:

### Romance Events
- `firstCrush` - Adolescence (chosen) vs. Relationships
- `dating_choice` - Adolescence (chosen) vs. Relationships
- `marriage` - Adulthood (chosen) vs. Relationships
- `wedding` - Adulthood (chosen) vs. Relationships

**Decision**: Split by life stage
- Teen romance → `adolescence/social.py`
- Adult romance → `adulthood/romance.py`

**Reasoning**: Life stage is the primary differentiator for gameplay purposes

### Job Events
- `firstJob` - Adulthood (chosen) vs. Education
- `employeeOfTheMonth` - Adulthood (chosen) vs. Random

**Decision**: All in `adulthood/career.py`

**Reasoning**: Jobs are primarily an adult life concept, even if first job is at 15-18

## Events That Fit Multiple Categories Well

These events had clear homes despite spanning concepts:

| Event | Category | Alt. Category | Reason Chosen |
|-------|----------|---------------|---------------|
| `braces` | adolescence/puberty | health/events | Physical development milestone |
| `glasses` | adolescence/puberty | health/events | Physical development milestone |
| `breakArm` | health/events | random/negative | Medical focus over randomness |
| `carCrash` | random/negative | health/events | Random accident over health |
| `freeConcert` | random/positive | holidays/annual | Truly random vs. calendar event |

## Recommendations for Future Events

When adding new events, use this decision tree:

1. **Is it tied to a specific age/life stage?**
   - Yes → childhood, adolescence, adulthood
   - No → Continue to #2

2. **Is it tied to education/school?**
   - Yes → education, school_year
   - No → Continue to #3

3. **Is it calendar/date-based?**
   - Yes → holidays
   - No → Continue to #4

4. **Is it health/medical?**
   - Yes → health
   - No → Continue to #5

5. **Is it a moral/ethical choice?**
   - Yes → dilemmas
   - No → Continue to #6

6. **Is it a conversation?**
   - Yes → conversations
   - No → Continue to #7

7. **Is it random/unexpected?**
   - Yes → random (positive or negative)
   - No → Consider creating new category

## Summary

**Most events had clear categories**. The main challenges were:
1. School year events that span multiple themes
2. Social events that could be relationships or life stages
3. Events that are both health-related and random

**Solutions**:
- Grouped school events together by timing/context
- Split romance by life stage (teen vs. adult)
- Prioritized primary purpose over secondary characteristics

**Future Work**:
- Consider creating `relationships/` folder for social events
- Consider splitting large `school_year/transitions.py` file
- Consider renaming ambiguous events (lowEnergyEvent vs lowEnergyEvents)