Revamp README for improved clarity and comprehensive feature documentation
- Expanded feature descriptions to highlight JSON and Markdown export capabilities. - Enhanced installation and usage sections with detailed instructions and examples. - Added sections for export formats, schema, troubleshooting, and development file structure. - Improved Markdown table and talent export documentation for guides and Wiki.js integration.
This commit is contained in:
+146
-44
@@ -1,54 +1,156 @@
|
||||
AscensionExporter
|
||||
=================
|
||||
|
||||
Export the following from your Ascension (WotLK 3.3.5) client:
|
||||
- Active talents (current spec only)
|
||||
- Worn items (equipped gear only), including base enchant text and gems
|
||||
- Active Mystic/Mythic Enchants (derived from equipped item tooltips)
|
||||
Export character data from your Ascension (WotLK 3.3.5) client for use in guides and documentation.
|
||||
|
||||
Installation (Linux path provided by you)
|
||||
- Copy the `AscensionExporter` folder to:
|
||||
`/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter`
|
||||
- Ensure the structure is:
|
||||
`/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter/AscensionExporter.toc`
|
||||
## Features
|
||||
|
||||
Usage
|
||||
- In-game, type:
|
||||
- `/ascx export all` — talents + gear + mystic enchants
|
||||
- `/ascx export talents` — only active spec selected talents
|
||||
- `/ascx export gear` — only equipped gear
|
||||
- `/ascx export enchants` — only mystic enchants
|
||||
- `/ascx export mdgear` — equipped gear as a Markdown table (for guides)
|
||||
- A copyable JSON window will open. Press Ctrl+C to copy.
|
||||
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
|
||||
|
||||
Export window button
|
||||
- The export window now has a "MD Gear" button. Click it to populate the window with a Markdown gear table matching the guide format:
|
||||
- Columns: `Slot | Item | Location | Enchant | Alternative`
|
||||
- `Item` links to db.ascension.gg when the itemId is known.
|
||||
- `Enchant` includes base enchant text and any active Mystic/Mythic enchant (e.g., `... / Mystic: Rune of Power`).
|
||||
- `Location` and `Alternative` are placeholders (`-`) since those are guide-specific.
|
||||
## Installation
|
||||
|
||||
SavedVariables (optional)
|
||||
- Disabled by default. Toggle with:
|
||||
- `/ascx sv on` — enable saving last export to SavedVariables
|
||||
- `/ascx sv off` — disable
|
||||
- Saved in: `AscensionExporterSaved` table (path depends on your client setup).
|
||||
Copy the `AscensionExporter` folder to your AddOns directory:
|
||||
```
|
||||
/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter
|
||||
```
|
||||
|
||||
JSON schema (v1)
|
||||
- Top-level fields:
|
||||
- `schemaVersion` (number)
|
||||
- `exportedAt` (ISO UTC string)
|
||||
- `client` (interface/build info)
|
||||
- `character` (name, realm, level, class, race, faction)
|
||||
- `talents` → `{ activeTalentGroup, selected[] }` for current spec only
|
||||
- `gear` → `{ slots[] }` equipped items with parsed IDs, names, enchant text, gems
|
||||
- `mysticEnchants` → `{ perSlot[], active[] }` from equipped item tooltips
|
||||
Ensure the structure is:
|
||||
```
|
||||
/srv/add01/wow-ascension/Interface/AddOns/AscensionExporter/AscensionExporter.toc
|
||||
```
|
||||
|
||||
Notes & limits
|
||||
- Mystic vs Mythic wording varies; detection is case-insensitive for lines containing both `mystic|mythic` and `enchant|rune`.
|
||||
- Profession-only enchants (e.g., Enchanting ring enchants) are not included in `mysticEnchants`; base enchant text is placed under `gear.slots[].enchant`.
|
||||
- Some item info may be `nil` if not cached; reopen the character pane or shift-hover items to cache if needed.
|
||||
## Usage
|
||||
|
||||
Troubleshooting
|
||||
- If `/ascx` doesn’t respond, verify the addon is enabled on the character select screen.
|
||||
- If the export window is empty, try `/reload` and re-run the command out of combat.
|
||||
### 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()`
|
||||
|
||||
Reference in New Issue
Block a user