Fairy

A Go library for fetching and enriching Zenless Zone Zero player profiles

Fetch and enrich Zenless Zone Zero player profiles via the EnkaNetwork API with localized names, calculated agent stats, and ready-to-use assets.

---

Installation

Requires Go 1.22+

go get github.com/kirinyoku/fairy

---

Quick Start

Fetch a player's showcase profile and inspect their agents with zero configuration:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/kirinyoku/fairy"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    profile, err := fairy.GetProfile(ctx, "1504687050")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Player: %s (Inter-Knot Lv.%d • %s)\n",
        profile.Nickname, profile.InterknotLevel, profile.Region)

    for _, agent := range profile.Agents {
        fmt.Printf("  • %s Lv.%d [%s / %s]\n",
            agent.Name, agent.Level, agent.AttributeName, agent.SpecialtyName)
    }
}

Player: LOWLEVEL (Inter-Knot Lv.60 • Europe)
  • Nangong Yu Lv.60 [Ether / Stun]
  • Yixuan Lv.60 [Auric Ink / Rupture]
  • Ye Shunguang Lv.60 [Honed Edge / Attack]
  • Harumasa Lv.60 [Electric / Attack]
  • Miyabi Lv.60 [Frost / Anomaly]
  • Remielle Lv.60 [Lumiflux / Anomaly]

---

Why Fairy?

The raw EnkaNetwork API returns internal numeric IDs, unlabeled stat keys, and unparsed Unity formula strings. Building apps directly on top of it requires maintaining mapping tables and stat formulas across every game patch.

Fairy handles all of this automatically in-memory.

🔍 Click to compare: Raw EnkaNetwork API vs Fairy Enriched Output

Raw EnkaNetwork API

Fairy Enriched Output

{ "Id": 1511, "Level": 60, "Exp": 0, "PromotionLevel": 6, "TalentLevel": 0, "SkinId": 3115111, "UpgradeId": 0, "CoreSkillEnhancement": 6, "Weapon": { "Id": 15388, "Level": 60, "StarMark": 1, "BreakLevel": 6 }, "EquippedList": [{ "Slot": 1, "Equipment": { "Id": 33041, "Level": 15, "MainPropertyList": [{ "PropertyId": 11103, "PropertyValue": 550 }], "RandomPropertyList": [ {"PropertyId": 12103, "PropertyValue": 19}, {"PropertyId": 31203, "PropertyValue": 9}, {"PropertyId": 11102, "PropertyValue": 300}, {"PropertyId": 12102, "PropertyValue": 300} ] } }] }

{ "name": "Nangong Yu", "level": 60, "rarity": "S", "attribute_name": "Ether", "specialty_name": "Stun", "w_engine": { "name": "Neon Fantasies", "level": 60, "modification": 1, "rarity": "S", "main_stat": { "name": "Base ATK", "value": 713 } }, "drive_discs": { "slots": [{ "slot": 1, "set": {"id": 33000, "name": "Phaethon's Melody"}, "level": 15, "main_stat": {"property_id": 11103, "name": "HP", "value": 2200, "is_percent": false}, "sub_stats": [ {"property_id": 12103, "name": "ATK", "value": 38, "is_percent": false, "rolls": 2}, {"property_id": 31203, "name": "Anomaly Prof", "value": 27, "is_percent": false, "rolls": 3}, {"property_id": 12102, "name": "ATK", "value": 0.09, "is_percent": true, "rolls": 3} ] }], "set_bonuses": [{ "set": {"id": 33000, "name": "Phaethon's Melody"}, "count": 4 }] }, "stats": { "hp": 11188, "atk": 2866, "crit_rate": 0.074, "crit_dmg": 0.548, "pen_ratio": 0.24, "energy_regen": 1.2 } }

Note: JSON snippets are simplified for illustration. Fairy's models provide complete asset URLs, formulas, and breakdown fields.

---

Core API

Fairy provides global functions for quick one-liners, and a Client struct for full control over networking, caching, and default language.

Method	Description	Network
fairy.GetProfile(ctx, uid)	Fetch, enrich, and return player profile as *fairy.Profile in default language	🌐 HTTP
fairy.GetProfileWithLang(ctx, uid, lang)	Fetch, enrich, and return player profile as *fairy.Profile in a specific language	🌐 HTTP
fairy.GetRawProfile(ctx, uid)	Fetch raw unparsed profile (*zzz.Profile) directly from EnkaNetwork API via enkanetwork-go	🌐 HTTP
fairy.Enrich(raw)	Transform raw profile (*zzz.Profile) into an enriched model (*fairy.Profile) in default language	⚡ In-memory
fairy.EnrichWithLang(raw, lang)	Transform raw profile (*zzz.Profile) into an enriched model (*fairy.Profile) in a specific language	⚡ In-memory
fairy.EnrichAgent(raw)	Transform raw avatar data (*zzz.AvatarData) into an enriched Agent model (*fairy.Agent) in default language	⚡ In-memory
fairy.EnrichAgentWithLang(raw, lang)	Transform raw avatar data (*zzz.AvatarData) into an enriched Agent model (*fairy.Agent) in a specific language	⚡ In-memory

---

Feature Highlights

1. Agent Stats — 3 Flexible Representations

Fairy calculates the complete combat stat sheet from base attributes, W-Engines, and Drive Discs:

Mode	Accessor	Type	Best for
Numeric	agent.Stats	Stats	Math calculations, damage simulators (CritRate: 0.05)
Formatted	agent.Stats.Formatted()	FormattedStats	Text output, logs, summaries (CritRate: "5.0%")
UI Breakdown	agent.UIStats	UIStats	In-game style Base + Added = Total with SVG icons & localized names

📖 See ExampleUIStats_List

---

2. Drive Disc Analysis & Build Scoring

Deep breakdown of Drive Disc sets, substat aggregations, and roll quality:

• Partition Slots (1–6): Main stats, substats, upgrade rolls, and set identifiers via agent.DriveDiscs.Slots.
• Set Bonuses: Active 2-pc and 4-pc set bonuses via agent.DriveDiscs.SetBonuses, or boolean queries via Has4Piece(setID) / Has2Piece(setID) (e.g. fairy.SetPolarMetal).
• Substat Totals: Aggregates all rolls and stat values across all discs with agent.DriveDiscs.SubStatTotals().
• Roll Scoring: Count effective rolls for specific priority stats with agent.DriveDiscs.CountEffectiveRolls(...).

📖 See ExampleDriveDiscs_SubStatTotals

---

3. Skills, Scaling & Rich Text

• Flat & Grouped Views: Access all abilities via agent.Skills, or categorized into the 6 in-game UI tabs (basic, special, dodge, chain, assist, passive) with upgrade levels (1–12 active, 0–6 core) via agent.SkillGroups.
• Dynamic Formulas: Scaling values and daze ratios are evaluated dynamically per skill level.
• Unity Rich Text: Built-in converters for in-game markup: FormatHTML(), FormatMarkdown(), or FormatPlainText().

📖 See ExampleAgent_SkillGroups

---

4. Mindscape Cinema & Potential Vision

• Mindscape Cinema: Constellation rank (M0–M6) via agent.MindscapeCinema.
• Node Tracking: Access all 6 Mindscape nodes with unlock status and formatted effect descriptions via agent.Mindscapes.
• Potential Vision: Character upgrade nodes with active unlock states via agent.PotentialVision.

📖 See ExampleAgent_Mindscapes

---

5. Player Showcase & Visual Assets

• Profile Info: Player Nickname, Inter-Knot Level, Server Region, and Server Cache TTL via profile.CacheTTL().
• Gradient Titles: Two-color gradient titles with hex color helpers (PrimaryColorHex(), SecondaryColorHex()).
• Media CDN Assets: Direct URLs for high-resolution splash art (agents & skins), W-Engines, discs, badges, namecards, plus vector SVG stat & attribute icons.

📖 See ExampleProfile

---

Advanced Configuration & Errors

🔧 Custom Client (Timeouts, Retries, Caching, User-Agent)

Use fairy.NewClient with functional options for production deployments:

// import "github.com/kirinyoku/enkanetwork-go/client/zzz"

client, err := fairy.NewClient(
    fairy.WithDefaultLang(fairy.LangJA),
    fairy.WithEnkaOptions(zzz.Options{
        UserAgent:  "MyApp/1.0 (contact@example.com)",
        HTTPClient: &http.Client{Timeout: 10 * time.Second},
        Retry:      &zzz.RetryOptions{MaxAttempts: 2, Delay: 2 * time.Second},
        // Cache: myCacheInstance, // plug in your own zzz.Cache implementation
    }),
)

profile, err := client.GetProfile(ctx, "1504687050")

🚨 Error Handling & Sentinel Errors

Fairy returns structured sentinel errors for reliable error handling with errors.Is:

Error	Description
fairy.ErrInvalidUID	UID format is invalid (must be 10 numeric digits starting with 10, 13, 15, or 17).
fairy.ErrProfileNotFound	The requested profile does not exist or has showcase hidden.
fairy.ErrRateLimit	EnkaNetwork API rate limit exceeded.
fairy.ErrMaintenance	API or game servers are under maintenance.
fairy.ErrNetwork	Network-level failure (DNS, connection timeout, etc.).
fairy.ErrEnrichment	In-memory metadata mapping or formula evaluation error.

---

Supported Languages

Fairy includes zero-config in-memory localization for all 13 official languages — embedded directly into the binary with no extra network requests.

🌐 Supported Languages Table

Language	Native Name	Constant	Code
English	English	fairy.LangEN	"en"
Russian	Русский	fairy.LangRU	"ru"
Japanese	日本語	fairy.LangJA	"ja"
Chinese (Simplified)	简体中文	fairy.LangZHCN	"zh-cn"
Chinese (Traditional)	繁體中文	fairy.LangZHTW	"zh-tw"
Korean	한국어	fairy.LangKO	"ko"
German	Deutsch	fairy.LangDE	"de"
French	Français	fairy.LangFR	"fr"
Spanish	Español	fairy.LangES	"es"
Portuguese	Português	fairy.LangPT	"pt"
Indonesian	Bahasa Indonesia	fairy.LangID	"id"
Thai	ภาษาไทย	fairy.LangTH	"th"
Vietnamese	Tiếng Việt	fairy.LangVI	"vi"

---

License

Fairy is released under the MIT License.