ShadowrunCharSheet/implementation-plan-98.md

Implementation Plan: Matrix attributes and hacking rules support (#98)

Issue Summary

Add support for Matrix-specific attributes for Deckers and Technomancers, including cyberdeck/commlink ASDF attributes (Attack, Sleaze, Data Processing, Firewall), Matrix initiative calculation, noise/signal tracking, device condition monitor, and Living Persona stats for Technomancers.

Requirements

Explicit Requirements

1. Data model for Matrix device with ASDF attributes (Attack, Sleaze, Data Processing, Firewall)
2. Matrix initiative calculated correctly (Data Processing + Intuition + dice)
3. Device condition monitor
4. UI section for Matrix stats
5. Serialization support

Derived Requirements

• Schema version migration from v0.7 to v0.8
• Integration with existing Attributes system for initiative calculation
• Backward compatibility with existing saved characters (empty/null Matrix device)
• Noise and signal tracking fields
• Living Persona support for Technomancers
• String resources for all UI labels
• Test tags for new UI components
• Tests for model, serialization, and migration

Assumptions

• A character has at most one active Matrix device (cyberdeck, commlink, or RCC)
• Living Persona is a special device type where ASDF comes from mental attributes
• Matrix condition monitor = 8 + (Device Rating / 2), following SR5e rules
• Matrix initiative = Data Processing + Intuition + Xd6 (updating existing placeholder)

Design Decisions

Device Model Structure

Chosen: A single MatrixDevice data class with a MatrixDeviceType enum (Commlink, Cyberdeck, RCC, LivingPersona). The device holds ASDF attributes, device rating, noise modifier, and current matrix damage. This is simple, serializable, and consistent with how other gear models (Weapon, Armor) are structured in the project.

Where to store Matrix data

Chosen: Add an optional matrixDevice: MatrixDevice? = null field on ShadowrunCharacter. This follows the pattern of optional subsystems (like spells, adeptPowers) and keeps backward compatibility clean.

Matrix Initiative Calculation

Chosen: Update Attributes.matrixInitiative() to accept a data processing value parameter (defaulting to current behavior). The ShadowrunCharacter will provide a convenience method that combines the device's Data Processing with the character's Intuition. The CombatTracker can use this for Matrix combat initiative.

Implementation Steps

Step 1: Create MatrixDevice data model

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/matrix/MatrixDevice.kt
• Create MatrixDeviceType enum: Commlink, Cyberdeck, RCC, LivingPersona
• Create MatrixDevice data class with: name, type, deviceRating, attack, sleaze, dataProcessing, firewall, noiseModifier, currentMatrixDamage
• Device condition monitor max = 8 + (deviceRating / 2)
• Include validation in init block

Step 2: Update ShadowrunCharacter

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/charactermodel/ShadowrunCharacter.kt
• Add matrixDevice: MatrixDevice? = null field
• Add matrixInitiative() method that returns Data Processing + Intuition
• Add matrixConditionMonitorMax() convenience method
• Add deviceConditionMonitorCurrent() convenience method

Step 3: Update Attributes.matrixInitiative()

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/attributes/Attributes.kt
• Update matrixInitiative() to accept an optional dataProcessing: Int parameter
• Formula: dataProcessing + intuition (base, before dice)

Step 4: Schema version migration v0.7 -> v0.8

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/migration/SchemaVersion.kt - Add V0_8
• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/migration/MigrationV07ToV08.kt - New migration
• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/model/migration/MigrationRegistry.kt - Register new migration
• Migration adds null/absent matrixDevice field (which defaults to null on deserialization)

Step 5: Add string resources

• File: sharedUI/src/commonMain/composeResources/values/strings.xml
• Add strings for Matrix panel: title, device type labels, ASDF labels, condition monitor, noise, etc.

Step 6: Add test tags

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/lib/components/TestTags.kt
• Add Matrix panel test tags

Step 7: Create MatrixPanel UI

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/lib/components/charactermodel/MatrixPanel.kt
• Display Matrix device stats: ASDF attributes, device rating, condition monitor
• Edit dialog for adding/editing a Matrix device
• Noise modifier display
• Condition monitor damage tracking

Step 8: Add Matrix tab to CharacterSheetPage

• File: sharedUI/src/commonMain/kotlin/org/shahondin1624/lib/components/charactermodel/CharacterSheetPage.kt
• Add Matrix tab to CharacterTab enum
• Add MatrixContent composable
• Wire up in both compact and expanded layouts

Step 9: Write tests

• File: sharedUI/src/commonTest/kotlin/org/shahondin1624/MatrixDeviceTest.kt
• Test MatrixDevice creation, validation, condition monitor calculation
• Test ShadowrunCharacter matrix initiative
• Test serialization round-trip
• Test migration v0.7 -> v0.8

Testing Strategy

• Unit tests for MatrixDevice model (creation, validation, condition monitor)
• Unit tests for matrix initiative calculation
• Serialization round-trip test
• Migration test for v0.7 -> v0.8
• Pre-existing test failures (29) should not increase

Migration & Compatibility

• Characters without Matrix devices will have matrixDevice = null (Kotlin default)
• Migration v0.7 -> v0.8 updates version fields; matrixDevice defaults to null on deserialization
• No breaking changes to existing data