# Fighter Advancements The fighter advancement system allows players to spend experience points (XP) to improve their fighters in campaign mode. This document describes the implementation and usage of the advancement system. ## Overview Advancements are improvements that fighters can purchase using XP earned during campaigns. The system uses a multi-step wizard interface that guides players through: 1. **Dice Rolling Choice** - Choose between random rolling (cheaper) or manual selection (more expensive) 2. **Advancement Selection** - Pick a specific advancement based on dice roll or manual choice 3. **Confirmation** - Review and confirm the advancement purchase There are two main types of advancements: * **Characteristic Increases** - Improve fighter stats like Movement, Weapon Skill, etc. * **New Skills** - Learn skills from Primary, Secondary, or other skill categories ## Model Structure ### ListFighterAdvancement The `ListFighterAdvancement` model tracks all advancements purchased by a fighter: ```python class ListFighterAdvancement(AppBase): fighter = models.ForeignKey(ListFighter, ...) advancement_type = models.CharField(...) # "stat" or "skill" stat_increased = models.CharField(...) # For stat advancements skill = models.ForeignKey(ContentSkill, ...) # For skill advancements xp_cost = models.PositiveIntegerField(...) cost_increase = models.IntegerField(...) campaign_action = models.OneToOneField("CampaignAction", ...) ``` Key features: * Tracks which fighter purchased the advancement * Records the type of advancement (stat or skill) * For stat advances: which characteristic was improved * For skill advances: which skill was gained * Tracks XP cost and any increase to the fighter's credit value * Links to campaign action if dice were rolled ### XP Tracking Fighters track their XP using two fields: * `xp_total` - Total XP earned throughout the campaign * `xp_current` - Available XP that can be spent When an advancement is purchased, the XP cost is deducted from `xp_current`. ## Form Flow The advancement system uses a wizard-style interface with these steps: ### Step 1: Start (`list_fighter_advancement_start`) Initiates the advancement process and redirects to dice choice. ### Step 2: Dice Choice (`list_fighter_advancement_dice_choice`) `AdvancementDiceChoiceForm` - Player chooses: * **Roll 2D6** - Cheaper option, limits choices based on dice result * **Manual Selection** - More expensive, allows any advancement ### Step 3: Type Selection (`list_fighter_advancement_type`) `AdvancementTypeForm` - Based on dice roll (or manual choice), shows available advancements: * Stat improvements (Movement, Weapon Skill, etc.) * Skill options (Primary/Secondary, Random/Chosen) * Special options (Promote to Specialist, Any Random Skill) Each option shows its XP cost based on the roll-to-cost mapping. ### Step 4: Skill Selection (`list_fighter_advancement_select`) If a skill advancement was chosen: * `SkillSelectionForm` - Pick specific skill from available categories * `RandomSkillForm` - Accept randomly rolled skill ### Step 5: Confirmation (`list_fighter_advancement_confirm`) Reviews the selected advancement showing: * What was selected * XP cost * Credit increase * Option to confirm or cancel ## Views The advancement system uses these views: * `list_fighter_advancements` - Lists all advancements for a fighter * `list_fighter_advancement_start` - Initiates the advancement wizard * `list_fighter_advancement_dice_choice` - Handles dice vs manual selection * `list_fighter_advancement_type` - Shows available advancement options * `list_fighter_advancement_select` - Skill selection for skill advancements * `list_fighter_advancement_confirm` - Final confirmation and purchase * `list_fighter_xp_edit` - Modify fighter's XP directly ## Business Rules ### XP Costs The system uses a dice roll to XP cost mapping: * Rolling 2-4, 12: 20 XP (includes special advancements) * Rolling 5-6: 30 XP (high-value stat increases) * Rolling 7, 10-11: 10 XP (moderate improvements) * Rolling 8-9: 5 XP (cheapest options) * Manual selection: Additional cost on top of base costs Default advancement for each roll: * 2, 12: Promote to Specialist * 3: Weapon Skill, 4: Ballistic Skill, 5: Strength * 6: Toughness, 7: Movement, 8: Willpower * 9: Intelligence, 10: Leadership, 11: Cool ### Stat Improvements * Stats with "+" values (like WS 4+) improve by reducing the number * Other stats increase numerically * Applied via fighter stat overrides ### Skill Restrictions * Can only learn skills from Primary or Secondary categories * Cannot learn the same skill twice * Some skills may have prerequisites ### Campaign Mode Only * Advancements can only be purchased in campaign mode * Requires active campaign participation ## Templates Key templates: * `list_fighter_advancements.html` - Shows all advancements for a fighter * `list_fighter_advancement_dice_choice.html` - Dice vs manual selection * `list_fighter_advancement_type.html` - Advancement options based on roll * `list_fighter_advancement_select.html` - Skill selection interface * `list_fighter_advancement_confirm.html` - Final confirmation screen ## Integration Points ### Campaign Actions When dice are rolled for an advancement, it creates a `CampaignAction` record to track: * Who rolled * What was rolled (2d6, 2d6+2) * Results * Links back to the advancement ### Fighter Cost Each advancement increases the fighter's cost: * Stat increases: typically +5 credits per stat point * Skills: varies by skill value ### History Tracking All advancement records use django-simple-history for audit trails. ## Example Usage ```python # Check if fighter can purchase advancements if fighter.list.status == List.CAMPAIGN_MODE and fighter.xp_current > 0: # Fighter can buy advancements # Apply an advancement advancement = ListFighterAdvancement.objects.create( fighter=fighter, advancement_type=ListFighterAdvancement.ADVANCEMENT_STAT, stat_increased="weapon_skill", xp_cost=6, cost_increase=5 ) advancement.apply_advancement() # Applies the stat increase ``` ## Frontend Behavior * Uses a multi-page wizard flow (not modals) * Session storage tracks advancement state between steps * Shows dice rolls and available options dynamically * Validates selections at each step * Allows going back to previous steps ## Error Handling Common validation errors: * Insufficient XP * Invalid stat/skill selection * Attempting advancement outside campaign mode * Duplicate skill selection All errors display user-friendly messages guiding correct usage. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://gyrinx.gitbook.io/gyrinx/technical-reference/fighter-advancements.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.