ascension-char-exporter/AscensionExporter/README.md

AscensionExporter
=================

Export character data from your Ascension (WotLK 3.3.5) client for use in guides and documentation.

## Features

Export the following from your character:
- **Talents**: Full talent build using Ascension's native format
- **Gear**: Equipped items with enchants and gems
- **Mystic Enchants**: Active Mystic/Mythic enchants from equipped items

## Installation

Copy the `AscensionExporter` folder to your AddOns directory:
```
/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter
```

Ensure the structure is:
```
/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter/AscensionExporter.toc
```

## Usage

### Slash Commands

In-game, type `/ascx` followed by:

#### JSON Export
- `/ascx export all` — Export talents + gear + mystic enchants as JSON
- `/ascx export talents` — Export only talent build
- `/ascx export gear` — Export only equipped gear
- `/ascx export enchants` — Export only mystic enchants

#### Markdown Export (for Wiki.js/guides)
- `/ascx export mdgear` — Gear table in Markdown format
- `/ascx export mdtalents` — Talent calculator link and embed code
- `/ascx export mdenchants` — Mystic enchants table in Markdown

#### Other Commands
- `/ascx sv on|off` — Toggle SavedVariables export (default: off)
- `/ascx debug` — Show collector status and diagnostics
- `/ascx help` — Show available commands

### Export Window Buttons

The export window includes quick-access buttons:
- **All** — Export everything as JSON
- **Talents** — Export talents as JSON
- **Gear** — Export gear as JSON
- **Enchants** — Export mystic enchants as JSON
- **MD Gear** — Generate Markdown gear table
- **MD Enchants** — Generate Markdown enchants table
- **MD Talents** — Generate Markdown talent calculator link

## Markdown Export Formats

### Gear Table (`mdgear`)
Generates a Markdown table with columns:
- **Slot** | **Item** | **Location** | **Enchant** | **Alternative**
- Items link to `db.ascension.gg` when itemId is known
- Enchants show base enchant + Mystic enchant (e.g., `+20 Spell Power / Mystic: Rune of Power`)
- Location and Alternative are placeholders (`-`) for manual editing

### Talent Export (`mdtalents`)
Generates:
- Clickable link: `[View in Talent Calculator](https://exil.es/en/wow/talent-calc?build=...)`
- Iframe embed code for Wiki.js pages
- Uses Ascension's native build format from `C_CharacterAdvancement.ExportBuild()`

### Mystic Enchants Table (`mdenchants`)
Generates a table with:
- **Quality** | **Enchant**
- Quality badges: Artifact, Legendary, Epic, Rare
- Enchant names with spell icons and links to `db.ascension.gg`
- Sorted by quality tier, then by slot

## JSON Export Schema (v1)

Top-level fields:
```json
{
  "schemaVersion": 1,
  "exportedAt": "2025-12-08T17:44:25Z",
  "client": { "interface": 30300, "version": "3.3.5", "build": "12340" },
  "character": { "name": "...", "realm": "...", "level": 60, "class": "MAGE", "race": "...", "faction": "..." },
  "talents": { "buildString": "NYzZFU...", "selected": [], "hasTalents": true },
  "gear": { "slots": [...] },
  "mysticEnchants": { "perSlot": [...], "active": [...], "enchants": [...] }
}
```

### Talents
- `buildString`: Ascension's native talent export (URL-encoded)
- `selected`: Legacy field for standard WoW talents (empty on Ascension)
- `hasTalents`: Boolean indicating if talents are present

### Gear
Each slot contains:
- `slot`: Slot ID (1=head, 2=neck, etc.)
- `itemId`: Database item ID
- `name`: Item name
- `enchant`: Base enchant text (e.g., "+20 Spell Power")
- `gems`: Array of gem IDs

### Mystic Enchants
- `perSlot`: Mystic enchants by gear slot
- `active`: All active mystic enchants
- `enchants`: Detailed enchant data (name, spellID, icon, slot, quality)

## SavedVariables (Optional)

Disabled by default. When enabled, exports are saved to `AscensionExporterSaved` keyed by `realm:character`.

Toggle with:
- `/ascx sv on` — Enable automatic saving
- `/ascx sv off` — Disable saving

## Notes & Limitations

- **Mystic Enchants**: Detection is case-insensitive for lines containing "mystic/mythic" and "enchant/rune"
- **Profession Enchants**: Ring enchants (Enchanting profession) are not included in mysticEnchants
- **Item Cache**: Some items may show as `nil` if not cached; open character panel or shift-hover items to cache
- **Talent API**: Uses Ascension's `C_CharacterAdvancement.ExportBuild()` API (standard WoW `GetTalentInfo` returns incorrect data on Ascension)

## Troubleshooting

- **Commands not working**: Verify addon is enabled on character select screen
- **Empty export window**: Try `/reload` and re-run command out of combat
- **Talents show as empty**: Ascension uses a custom talent system; the addon now uses `C_CharacterAdvancement.ExportBuild()`
- **Missing mystic enchants**: Only enchants on currently equipped items are detected

## Development

### File Structure
```
AscensionExporter/
├── AscensionExporter.toc
├── Core.lua                    # Main logic, slash commands, markdown generators
├── Collectors/
│   ├── Talents.lua            # Talent collector using C_CharacterAdvancement
│   ├── Gear.lua               # Gear collector
│   └── Enchants.lua           # Mystic enchant collector
├── Util/
│   ├── Json.lua               # JSON encoder
│   └── TalentEncoder.lua      # Legacy talent encoder (unused on Ascension)
└── UI/
    └── ExportFrame.lua        # Export window UI
```

### Version History
- **0.1.0**: Initial release with talents, gear, and mystic enchant export
- **0.2.0**: Added Markdown export formats for Wiki.js integration
- **0.3.0**: Fixed Ascension talent export using `C_CharacterAdvancement.ExportBuild()`