### Install Dependencies with Yarn

Source: https://github.com/yuko1101/enka-network-api/blob/main/docs/README.md

Installs project dependencies using Yarn. Run this command after cloning the repository.

```bash
yarn
```

--------------------------------

### Start Local Development Server

Source: https://github.com/yuko1101/enka-network-api/blob/main/docs/README.md

Starts a local development server for live preview. Changes are reflected without server restart.

```bash
yarn start
```

--------------------------------

### Install EnkaNetworkAPI via ghproxy.com

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Alternative installation method using ghproxy.com for npm packages.

```sh
npm install enka-network-api@latest --enka-ghproxy=true
```

--------------------------------

### Install EnkaNetworkAPI with Cache

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Install the library including Genshin cache data. Node.js 16 or newer is required.

```sh
npm install enka-network-api@latest
```

--------------------------------

### Install Enka Network API

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Install the package using npm. Use flags to skip cache download or use a specific mirror.

```sh
npm install enka-network-api@latest

# Skip cache download if already present elsewhere
npm install enka-network-api@latest --enka-nocache=true

# Use ghproxy mirror (China)
npm install enka-network-api@latest --enka-ghproxy=true
```

--------------------------------

### Install EnkaNetworkAPI without Cache Download

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Install the library without downloading the cache data, useful if cache is already managed.

```sh
npm install enka-network-api@latest --enka-nocache=true
```

--------------------------------

### Get Genshin Weapon List

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Fetches all available weapons from the Enka Network API. Requires EnkaClient initialization. Prints weapon names in Japanese.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

const weapons = enka.getAllWeapons();
// print weapon names in language "jp"
console.log(weapons.map(w => w.name.get("jp")));
```

--------------------------------

### Genshin Weapon List

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Retrieves a list of all available Genshin Impact weapons. The example shows how to access weapon names in Japanese.

```APIDOC
## EnkaClient#getAllWeapons

### Description
Retrieves a list of all available Genshin Impact weapons.

### Method
JavaScript (EnkaClient method)

### Endpoint
N/A (Client-side method)

### Parameters
None

### Request Example
```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

const weapons = enka.getAllWeapons();
// print weapon names in language "jp"
console.log(weapons.map(w => w.name.get("jp")));
```

### Response
#### Success Response
An array of weapon objects.

#### Response Example
(Example not provided in source, but would be an array of weapon objects)
```

--------------------------------

### EnkaClient: Get All Materials and Name Cards

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches all game materials, including upgrade items and food, and all player name cards. Allows lookup of specific materials or name cards by their IDs.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

const materials = enka.getAllMaterials();
console.log(`Total materials: ${materials.length}`);

// A specific material by ID
const juvenileJade = enka.getMaterialById(112012);
console.log(juvenileJade.name.get("en"));    // "Juvenile Jade"
console.log(`Stars: ${juvenileJade.stars}`);
console.log(juvenileJade.icon.url);          // resolved CDN URL

// Name cards (shown on player profiles)
const nameCards = enka.getAllNameCards();
console.log(`Name cards: ${nameCards.length}`);

const specificCard = enka.getNameCardById(210049);
console.log(specificCard.name.get("en"));
```

--------------------------------

### EnkaClient: Get All Costumes

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Lists all character costumes available in the game. Can optionally include default costumes, but by default only shows premium (non-default) ones.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// Non-default (premium) costumes only
const premiumCostumes = enka.getAllCostumes(false);
for (const costume of premiumCostumes) {
    const char = costume.getCharacterData();
    console.log(`${char.name.get("en")} — ${costume.name.get("en")}`);
    console.log(`  Icon: ${costume.icon.url}`);
}
// Kamisato Ayaka — Springbloom Missive
// Jean — Sea Breeze Dandelion
// …
```

--------------------------------

### TextAssets — multi-language text resolution

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Handles multi-language text resolution for names, descriptions, and skill texts. Supports 13 languages and provides methods to get text in a specific language or convert to HTML format.

```APIDOC
## TextAssets — multi-language text resolution

Every name, description, or skill text is a `TextAssets` that resolves for any of the 13 supported language codes.

### Method
- `get(languageCode: string)`: Retrieves the text for the specified language code.
- `getNullable(languageCode: string)`: Retrieves the text for the specified language code, returning null if not found.
- `setConvertToHtmlFormat(convertToHtml: boolean)`: Sets whether to convert HTML color tags.

### Example Usage
```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

const fischl = enka.getCharacterById(10000031);

// Supported languages: chs cht de en es fr id jp kr pt ru th vi
for (const lang of ["en", "jp", "de", "chs"]) {
    console.log(`[${lang}] ${fischl.name.get(lang)}`);
}
// [en] Fischl
// [jp] フィッシュル
// [de] Fischl
// [chs] 菲谢尔

// Description with HTML colour tags converted
const descHtml = fischl.description.setConvertToHtmlFormat(true).get("en");
console.log(descHtml); // "A mysterious traveler from <span style=\"color:#FFD780FF\">...</span>"

// getNullable() returns null instead of throwing when text is missing
const nullable = fischl.description.getNullable("kr");
```
```

--------------------------------

### EnkaClient: Get All Artifacts and Sets

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves all artifact data from the game cache without needing a UID. Useful for listing highest-rarity artifacts or iterating through all artifact sets and their bonuses.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// Get only highest-rarity artifacts (5★ versions only)
const fiveStarArtifacts = enka.getAllArtifacts(true);
console.log(`5★ artifact pieces: ${fiveStarArtifacts.length}`);

// Get all artifact sets
const sets = enka.getAllArtifactSets();
for (const set of sets.slice(0, 3)) {
    console.log(`${set.name.get("en")} — ${set.setBonus.length}-bonus set`);
    for (const bonus of set.setBonus) {
        console.log(`  ${bonus.needCount}pc: ${bonus.description.get("en").slice(0, 60)}…`);
    }
}

// Lookup a specific artifact by ID
const artifact = enka.getArtifactById(75004);
console.log(artifact.name.get("en"));
console.log(`Set: ${artifact.set.name.get("en")}`);
console.log(`Slot: ${artifact.equipType}`);
```

--------------------------------

### Get Character Skill Attributes and Levels

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves character skill attributes using static data and fetches live character skill levels from a user's profile. Requires EnkaClient and uses ElementalBurst#getSkillAttributes.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// Skill attributes from static game data (no UID fetch needed)
const nahida = enka.getCharacterById(10000073);
const burst = nahida.elementalBurst;
console.log(`Energy cost: ${burst.requiredCharge}`);

const attrs = burst.getSkillAttributes(10); // level 10
for (const attr of attrs) {
    const data = attr.getAttributeData("en");
    console.log(`${data.name} | ${data.valueText}`);
}
/* Output:
Pyro: DMG Bonus | 1 Character 27%
Base Duration | 15.0s
CD | 13.5s
Energy Cost | 50
*/

// Skill levels from a live character
(async () => {
    const user = await enka.fetchUser(825436941);
    const char = user.characters.find(c => c.characterData.name.get() === "Nahida");
    if (char) {
        for (const { skill, level } of char.skillLevels) {
            console.log(`${skill.name.get()}: Lv.${level.base}+${level.extra} (effective: ${level.base + level.extra})`);
        }
    }
    enka.close();
})();
```

--------------------------------

### Get All Playable Characters

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves a list of all playable characters with their associated data, including name, element, rarity, and skills. Useful for iterating through all characters or displaying a character list.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// List all playable characters
const allChars = enka.getAllCharacters();
console.log(`Total playable characters: ${allChars.length}`);
console.log(allChars.map(c => `${c.name.get()} (${c.element?.name.get() ?? "None"}) ${c.stars}★`).join("\n"));
```

--------------------------------

### Get All Genshin Characters

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Retrieve a list of all available Genshin Impact characters. The character names can be accessed in different languages.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

const characters = enka.getAllCharacters();
// print character names in language "en"
console.log(characters.map(c => c.name.get("en")));

```

--------------------------------

### CachedAssetsManager#activateAutoCacheUpdater

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Activates a background process that automatically checks for and downloads new Genshin game data updates. It can be configured to run immediately, set a check interval, and define callbacks for when updates start, end, or encounter errors.

```APIDOC
## CachedAssetsManager#activateAutoCacheUpdater — keep cache current automatically

Activates a background interval that checks for new Genshin game data and downloads it automatically after each update.

```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ cacheDirectory: "./cache" });

enka.cachedAssetsManager.activateAutoCacheUpdater({
    instant: true,                  // run update check immediately on activation
    timeout: 60 * 60 * 1000,        // check every hour (minimum: 1 minute)
    onUpdateStart: async () => {
        console.log("New Genshin data detected – downloading…");
    },
    onUpdateEnd: async () => {
        enka.cachedAssetsManager.refreshAllData(true); // reload in-memory cache
        console.log("Cache updated and reloaded.");
    },
    onError: async (err) => {
        console.error("Auto-update failed:", err.message);
    },
});

// Later, to stop:
// enka.cachedAssetsManager.deactivateAutoCacheUpdater();
```
```

--------------------------------

### Activate Automatic Cache Updates

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Keeps the Genshin game data cache current by automatically checking for and downloading updates. Configuration options include immediate checks, update intervals, and callbacks for update start, end, and errors.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ cacheDirectory: "./cache" });

enka.cachedAssetsManager.activateAutoCacheUpdater({
    instant: true,                  // run update check immediately on activation
    timeout: 60 * 60 * 1000,        // check every hour (minimum: 1 minute)
    onUpdateStart: async () => {
        console.log("New Genshin data detected – downloading…");
    },
    onUpdateEnd: async () => {
        enka.cachedAssetsManager.refreshAllData(true); // reload in-memory cache
        console.log("Cache updated and reloaded.");
    },
    onError: async (err) => {
        console.error("Auto-update failed:", err.message);
    },
});

// Later, to stop:
// enka.cachedAssetsManager.deactivateAutoCacheUpdater();
```

--------------------------------

### Build Static Website Content

Source: https://github.com/yuko1101/enka-network-api/blob/main/docs/README.md

Generates static website files into the 'build' directory, ready for hosting.

```bash
yarn build
```

--------------------------------

### Deploy Website using SSH

Source: https://github.com/yuko1101/enka-network-api/blob/main/docs/README.md

Deploys the website using SSH. Assumes SSH keys are configured for deployment.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### Initialize EnkaClient with Options

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Instantiate the EnkaClient with optional configuration. Always call close() when done to clear timers.

```javascript
const { EnkaClient } = require("enka-network-api");

const enka = new EnkaClient({
    defaultLanguage: "en",        // one of: chs cht de en es fr id jp kr pt ru th vi
    requestTimeout: 3000,         // ms, default 3000
    showFetchCacheLog: true,      // log cache download progress
    cacheDirectory: "./cache",    // custom cache path (default: node_modules/.../cache)
    githubToken: process.env.GH_TOKEN ?? null, // reduce GitHub API rate limits during update checks
    userCache: {
        isEnabled: true,
        // Optional custom storage (e.g. Redis). All three must be set together or left null.
        getter: async (key) => redis.get(key),
        setter: async (key, data) => redis.set(key, JSON.stringify(data)),
        deleter: async (key) => redis.del(key),
    },
});

// Always call close() to clear internal TTL timers when done
enka.close();
```

--------------------------------

### Handle Dynamic Text Assets with User Info

Source: https://github.com/yuko1101/enka-network-api/blob/main/CHANGELOG.md

Demonstrates how to use DynamicTextAssets to format strings with placeholders, including user-specific information like nickname and gender. Use `getReplacedText()` for formatted output and `copyWithUserInfo()` to update user context.

```javascript
const enka = new EnkaClient({
    defaultLanguage: "en",
    textAssetsDynamicData: {
        userInfo: {
            travelerGender: "FEMALE", // Lumine
            travelerNickname: "nickname",
            platform: "PC",
        }
    }
});

const dynamicTextAssets = /* example DynamicTextAssets, whose get() returns "#Hello {M:Mr}{F:Ms}.{NICKNAME}. {LAYOUT_MOBILE#Tap}{LAYOUT_PC#Press}{LAYOUT_PS#Press} the button." */

dynamicTextAssets.get();
// "#Hello {M:Mr}{F:Ms}.{NICKNAME}. {LAYOUT_MOBILE#Tap}{LAYOUT_PC#Press}{LAYOUT_PS#Press} the button."

dynamicTextAssets.getReplacedText();
// "Hello Ms.nickname. Press the button."

dynamicTextAssets.copyWithUserInfo({
    travelerGender: "MALE", // Aether
    travelerNickname: "Tom",
    platform: "MOBILE",
}).getReplacedText();
// "Hello Mr.Tom. Tap the button."
```

--------------------------------

### EnkaClient Constructor and Options

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Instantiate EnkaClient once per process. All options are optional.

```APIDOC
## EnkaClient Constructor

### Description
Instantiate the `EnkaClient` class. It's recommended to instantiate it once per process.

### Options
- **defaultLanguage** (string) - Optional - The default language for text assets. Defaults to 'en'.
- **requestTimeout** (number) - Optional - The request timeout in milliseconds. Defaults to 3000.
- **showFetchCacheLog** (boolean) - Optional - Whether to log cache download progress. Defaults to false.
- **cacheDirectory** (string) - Optional - Custom path for the cache directory. Defaults to `node_modules/.../cache`.
- **githubToken** (string | null) - Optional - A GitHub token to reduce rate limits during update checks. Defaults to null.
- **userCache** (object) - Optional - Configuration for user data caching.
  - **isEnabled** (boolean) - Whether user caching is enabled. Defaults to true.
  - **getter** (function) - An async function to retrieve cached user data.
  - **setter** (function) - An async function to set cached user data.
  - **deleter** (function) - An async function to delete cached user data.

### Method
```javascript
const { EnkaClient } = require("enka-network-api");

const enka = new EnkaClient({
    defaultLanguage: "en",
    requestTimeout: 3000,
    showFetchCacheLog: true,
    cacheDirectory: "./cache",
    githubToken: process.env.GH_TOKEN ?? null,
    userCache: {
        isEnabled: true,
        getter: async (key) => redis.get(key),
        setter: async (key, data) => redis.set(key, JSON.stringify(data)),
        deleter: async (key) => redis.del(key),
    },
});

// Always call close() to clear internal TTL timers when done
enka.close();
```
```

--------------------------------

### Get Specific Character by ID

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches detailed game data for a specific character using their numeric ID. For the Traveler, a `skillDepotId` is required to specify their element.

```javascript
// Fetch a specific character by numeric ID
const nahida = enka.getCharacterById(10000073);
console.log(nahida.name.get("en"));                     // "Nahida"
console.log(nahida.element?.name.get("en"));            // "Dendro"
console.log(nahida.rarity);                             // "QUALITY_ORANGE"
console.log(nahida.isTraveler);                         // false
console.log(nahida.arkhe);                              // null

// Traveler requires a skillDepotId to specify their element
const lumine = enka.getCharacterById(10000007, 704);    // 704 = Dendro Lumine
console.log(lumine.element?.name.get("en"));            // "Dendro"
```

--------------------------------

### Integrate EnkaClient with StarRail.js using EnkaSystem

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Use EnkaSystem to link Genshin Impact and Honkai: Star Rail clients, allowing a single Enka.Network account to query saved builds from both games. Both EnkaClient and StarRail instances automatically register with the EnkaSystem.

```javascript
const { EnkaSystem } = require("enka-system");
const { EnkaClient } = require("enka-network-api");
const { StarRail } = require("starrail.js");

// Both clients auto-register to EnkaSystem.instance
const enka = new EnkaClient({ defaultLanguage: "en" });
const sr = new StarRail();

(async () => {
    const accounts = await EnkaSystem.instance.fetchEnkaGameAccounts("EnkaUsername");
    for (const account of accounts) {
        const builds = await account.fetchBuilds();
        for (const build of Object.values(builds).flat()) {
            if (build.hoyoType === 0) { // Genshin Impact
                const c = build.character.characterData;
                console.log(`GI | ${c.name.get("en")} [${c.element?.name.get("en")}]`);
            } else if (build.hoyoType === 1) { // Honkai: Star Rail
                const c = build.character.characterData;
                console.log(`SR | ${c.name.get("en")} [${c.path.name.get("en")}]`);
            }
        }
    }
})();
```

--------------------------------

### DynamicTextAssets — skill descriptions with placeholder substitution

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Resolves dynamic skill descriptions that contain placeholders for stat values, gender-specific text, and platform hints. Allows for user info overrides for specific calls.

```APIDOC
## DynamicTextAssets — skill descriptions with placeholder substitution

Skill descriptions contain dynamic placeholders (stat values, gender-specific text, platform hints). `DynamicTextAssets` resolves them.

### Method
- `getReplacedText()`: Substitutes placeholders in the skill description.
- `copyWithUserInfo(userInfo: object)`: Creates a copy of the `DynamicTextAssets` with overridden user information for substitution.

### Example Usage
```js
const { EnkaClient } = require("enka-network-api");

const enka = new EnkaClient({
    defaultLanguage: "en",
    textAssetsDynamicData: {
        paramList: [],
        userInfo: {
            travelerGender: "FEMALE",  // "MALE" | "FEMALE"
            travelerNickname: "Lumine",
            platform: "PC",            // "MOBILE" | "PC" | "PS"
        },
    },
});

const traveler = enka.getCharacterById(10000007, 704); // Dendro Lumine
const normalAttack = traveler.normalAttack;

// getReplacedText() substitutes {param1:F1P}, {M:...}{F:...}, {NICKNAME}, {LAYOUT_PC#...} etc.
const desc = normalAttack.description.getReplacedText();
console.log(desc);

// Override user info for a specific call
const maleVersion = normalAttack.description.copyWithUserInfo({
    travelerGender: "MALE",
    travelerNickname: "Aether",
    platform: "PS",
}).getReplacedText();
```
```

--------------------------------

### Fetch Enka.Network Account Builds

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches saved character builds from an Enka.Network account. Use this to retrieve builds not currently showcased in-game. Requires the EnkaClient to be initialized.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    const accounts = await enka.fetchEnkaGenshinAccounts("EnkaUsername");

    for (const account of accounts) {
        const builds = await enka.fetchEnkaGenshinBuilds(account.username, account.hash);
        // builds is Record<characterId, GenshinCharacterBuild[]>
        for (const [charId, buildList] of Object.entries(builds)) {
            for (const build of buildList) {
                const char = build.character;
                console.log(`${char.characterData.name.get()} | Build: ${build.name ?? "unnamed"}`);
                console.log(`  Weapon: ${char.weapon.weaponData.name.get()} R${char.weapon.refinementRank}`);
            }
        }
    }
    enka.close();
})();
```

--------------------------------

### CachedAssetsManager#fetchAllContents

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Downloads all Genshin game data, including Excel files and text maps for all 13 languages, into the local cache directory. This can also be configured to fetch directly from the Dimbreath GitLab raw data repository.

```APIDOC
## CachedAssetsManager#fetchAllContents — download / update game data cache

Downloads all Genshin game data (excel files + all 13 language text maps) from GitHub into the cache directory.

```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ cacheDirectory: "./cache", showFetchCacheLog: true });

(async () => {
    // First run: download everything
    await enka.cachedAssetsManager.fetchAllContents();

    // Or fetch directly from the Dimbreath GitLab raw data repo instead of cache.zip
    await enka.cachedAssetsManager.fetchAllContents({ useRawGenshinData: true });
})();
```
```

--------------------------------

### Deploy Website without SSH

Source: https://github.com/yuko1101/enka-network-api/blob/main/docs/README.md

Deploys the website without using SSH. Requires specifying the GitHub username.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Fetch Fast Player Profile Overview

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches a fast player profile overview without character details. Useful for player cards and profile displays.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    const user = await enka.fetchCollapsedUser(825436941);

    console.log(`${user.nickname} | World Level ${user.worldLevel}`);
    console.log(`Characters on showcase:`);
    for (const preview of user.charactersPreview) {
        console.log(`  ${preview.costume.characterData.name.get()} Lv.${preview.level} (${preview.element?.name.get() ?? "?"}) C${preview.constellation ?? "?"}`);
    }
    enka.close();
})();

/* Example output:
yuko1101 | World Level 8
Characters on showcase:
  Hu Tao Lv.90 (Pyro) C1
  Raiden Shogun Lv.90 (Electro) C2
*/
```

--------------------------------

### EnkaClient#fetchEnkaGenshinAccounts / fetchEnkaGenshinBuilds

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches saved character builds from an Enka.Network account by username. It retrieves all builds associated with an account, including those not showcased in-game.

```APIDOC
## EnkaClient#fetchEnkaGenshinAccounts / fetchEnkaGenshinBuilds — Enka.Network account builds

Fetches saved character builds from an Enka.Network account (by username), including builds not currently showcased in-game.

```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    const accounts = await enka.fetchEnkaGenshinAccounts("EnkaUsername");

    for (const account of accounts) {
        const builds = await enka.fetchEnkaGenshinBuilds(account.username, account.hash);
        // builds is Record<characterId, GenshinCharacterBuild[]>
        for (const [charId, buildList] of Object.entries(builds)) {
            for (const build of buildList) {
                const char = build.character;
                console.log(`${char.characterData.name.get()} | Build: ${build.name ?? "unnamed"}`);
                console.log(`  Weapon: ${char.weapon.weaponData.name.get()} R${char.weapon.refinementRank}`);
            }
        }
    }
    enka.close();
})();
```
```

--------------------------------

### Download All Game Data Cache

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Downloads all Genshin game data, including excel files and language text maps, into a specified cache directory. Can optionally fetch directly from a raw data repository.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ cacheDirectory: "./cache", showFetchCacheLog: true });

(async () => {
    // First run: download everything
    await enka.cachedAssetsManager.fetchAllContents();

    // Or fetch directly from the Dimbreath GitLab raw data repo instead of cache.zip
    await enka.cachedAssetsManager.fetchAllContents({ useRawGenshinData: true });
})();
```

--------------------------------

### CharacterData#getAscensionData

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves ascension costs (mora and materials) and stat bonuses for a character at each ascension phase (0-6).

```APIDOC
## CharacterData#getAscensionData — ascension costs and stat bonuses

### Description
Returns a `CharacterAscension` containing mora cost, material requirements, and stat bonuses granted at each ascension phase (0–6).

### Method Signature
`character.getAscensionData(phase: number): CharacterAscension`

### Parameters
* **phase** (number) - Required - The ascension phase (1-6) for which to retrieve data.

### Response
* **CharacterAscension** - An object containing ascension costs and stat bonuses.
  * **cost.coin** (number) - The amount of mora required for the phase.
  * **cost.items** (Array<Object>) - An array of materials required for the phase.
    * **material.id** (string) - The ID of the material.
    * **material.name** (string) - The name of the material.
    * **count** (number) - The quantity of the material required.
  * **statBonuses** (Array<Object>) - An array of stat bonuses granted at this phase.
```

--------------------------------

### Export User Data to GOOD Format

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Export user data including characters, artifacts, and weapons into the Genshin Open Object Description (GOOD) format. This is useful for integrating with optimiser tools like Genshin Optimizer or Akasha System. The exported JSON includes format, version, and source information.

```javascript
const { EnkaClient } = require("enka-network-api");
const fs = require("fs");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    const user = await enka.fetchUser(825436941);
    const good = user.toGOOD();

    // good.format === "GOOD", good.version === 2, good.source === "yuko1101/enka-network-api"
    console.log(`Characters: ${good.characters.length}`);
    console.log(`Artifacts: ${good.artifacts.length}`);
    console.log(`Weapons: ${good.weapons.length}`);

    // Save for use in Genshin Optimizer or Akasha System
    fs.writeFileSync("good-export.json", JSON.stringify(good, null, 2));

    enka.close();
})();
/* good.characters[0] example:
{
  "key": "HuTao",
  "level": 90,
  "constellation": 1,
  "ascension": 6,
  "talent": { "auto": 10, "skill": 14, "burst": 14 }
}
*/
```

--------------------------------

### Configure Custom Cache Directory

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Set a custom directory for storing Genshin cache data. The default is node_modules/enka-network-api/cache.

```javascript
const { EnkaClient } = require("enka-network-api");

// Change the directory to store cache data.
// Default directory is node_modules/enka-network-api/cache.
const enka = new EnkaClient();
enka.cachedAssetsManager.cacheDirectoryPath = "./cache";
enka.cachedAssetsManager.cacheDirectorySetup();

// OR

const enka = new EnkaClient({ cacheDirectory: "./cache" });
enka.cachedAssetsManager.cacheDirectorySetup();

```

--------------------------------

### TextAssets: Multi-language Text Resolution

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Handles text assets like names and descriptions, resolving them for any of the 13 supported languages. Supports converting HTML color tags and safely retrieving text that might be missing.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

const fischl = enka.getCharacterById(10000031);

// Supported languages: chs cht de en es fr id jp kr pt ru th vi
for (const lang of ["en", "jp", "de", "chs"]) {
    console.log(`[${lang}] ${fischl.name.get(lang)}`);
}
// [en] Fischl
// [jp] フィッシュル
// [de] Fischl
// [chs] 菲谢尔

// Description with HTML colour tags converted
const descHtml = fischl.description.setConvertToHtmlFormat(true).get("en");
console.log(descHtml); // "A mysterious traveler from <span style="color:#FFD780FF">...</span>"

// getNullable() returns null instead of throwing when text is missing
const nullable = fischl.description.getNullable("kr");
```

--------------------------------

### EnkaClient#getAllWeapons

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves all available weapon game data, including name, type, stars, and stat calculations.

```APIDOC
## EnkaClient#getAllWeapons — weapon game data

### Description
Returns `WeaponData` with name, type, stars, refinements, and stat calculation across any ascension/level.

### Method Signature
`enkaClient.getAllWeapons(): Array<WeaponData>

### Response
* **Array<WeaponData>** - An array of all available weapon data objects.
  * **name** (string) - The name of the weapon.
  * **type** (string) - The type of the weapon (e.g., Sword, Claymore).
  * **stars** (number) - The rarity of the weapon (1-5 stars).
  * **refinements** (Array<Refinement>) - An array of refinement descriptions.
  * **getStats(ascension: number, level: number): Array<Stat>** - Calculates weapon stats at a given ascension and level.
```

--------------------------------

### Calculate Total Ascension Costs for a Character

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Calculates the total mora and material costs required to fully ascend a character from phase 1 to 6. Requires importing EnkaClient and using CharacterData#getAscensionData.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

const xiao = enka.getCharacterById(10000026);

let totalMora = 0;
const materialTotals = {};

for (let phase = 1; phase <= 6; phase++) {
    const asc = xiao.getAscensionData(phase);
    totalMora += asc.cost.coin;
    for (const item of asc.cost.items) {
        materialTotals[item.material.id] ??= { name: item.material.name.get(), count: 0 };
        materialTotals[item.material.id].count += item.count;
    }
}

console.log(`Total mora to fully ascend Xiao: ${totalMora.toLocaleString()}`);
for (const { name, count } of Object.values(materialTotals)) {
    console.log(`  ${name}: ${count}`);
}
/* Output:
Total mora to fully ascend Xiao: 420,000
  Qingxin: 168
  Vayuda Turquoise Sliver: 1
  Vayuda Turquoise Fragment: 9
  …
*/
```

--------------------------------

### DynamicTextAssets: Skill Description Substitution

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Resolves skill descriptions that contain dynamic placeholders such as stat values, gender-specific text, or platform hints. Allows overriding user information for specific calls.

```javascript
const { EnkaClient } = require("enka-network-api");

const enka = new EnkaClient({
    defaultLanguage: "en",
    textAssetsDynamicData: {
        paramList: [],
        userInfo: {
            travelerGender: "FEMALE",  // "MALE" | "FEMALE"
            travelerNickname: "Lumine",
            platform: "PC",            // "MOBILE" | "PC" | "PS"
        },
    },
});

const traveler = enka.getCharacterById(10000007, 704); // Dendro Lumine
const normalAttack = traveler.normalAttack;

// getReplacedText() substitutes {param1:F1P}, {M:...}{F:...}, {NICKNAME}, {LAYOUT_PC#...} etc.
const desc = normalAttack.description.getReplacedText();
console.log(desc);

// Override user info for a specific call
const maleVersion = normalAttack.description.copyWithUserInfo({
    travelerGender: "MALE",
    travelerNickname: "Aether",
    platform: "PS",
}).getReplacedText();
```

--------------------------------

### EnkaClient#getAllMaterials / getMaterialById / getAllNameCards

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves all game materials, including upgrade materials, food, and name cards. Supports fetching all materials, a specific material by ID, and all name cards.

```APIDOC
## EnkaClient#getAllMaterials / getMaterialById / getAllNameCards — material data

Retrieves all game materials including upgrade materials, food, and name cards.

### Method
- `getAllMaterials()`: Retrieves all game materials.
- `getMaterialById(id: number)`: Retrieves a specific material by its ID.
- `getAllNameCards()`: Retrieves all name cards.
- `getNameCardById(id: number)`: Retrieves a specific name card by its ID.

### Example Usage
```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

const materials = enka.getAllMaterials();
console.log(`Total materials: ${materials.length}`);

// A specific material by ID
const juvenileJade = enka.getMaterialById(112012);
console.log(juvenileJade.name.get("en"));    // "Juvenile Jade"
console.log(`Stars: ${juvenileJade.stars}`);
console.log(juvenileJade.icon.url);          // resolved CDN URL

// Name cards (shown on player profiles)
const nameCards = enka.getAllNameCards();
console.log(`Name cards: ${nameCards.length}`);

const specificCard = enka.getNameCardById(210049);
console.log(specificCard.name.get("en"));
```
```

--------------------------------

### Fetch Detailed Player Profile

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches a full player profile including character builds. Handles potential EnkaNetworkError, UserNotFoundError, or InvalidUidFormatError.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    try {
        const user = await enka.fetchUser(825436941);

        console.log(`${user.nickname} (AR${user.level})`);
        console.log(`Profile card: ${user.profileCard.name.get()}`);
        console.log(`Achievements: ${user.achievements}`);
        console.log(`Spiral Abyss: Floor ${user.spiralAbyss?.floor}-${user.spiralAbyss?.chamber} (${user.spiralAbyss?.stars}★)`);
        console.log(`Imaginarium Theater: Act ${user.theater?.act} (${user.theater?.stars}★)`);

        for (const char of user.characters) {
            console.log(`  ${char.characterData.name.get()} Lv.${char.level}/${char.maxLevel} C${char.unlockedConstellations.length}`);
        }
    } catch (e) {
        // EnkaNetworkError, UserNotFoundError, InvalidUidFormatError
        console.error(e.message);
    } finally {
        enka.close();
    }
})();

/* Example output:
yuko1101 (AR60)
Profile card: Hu Tao
Achievements: 982
Spiral Abyss: Floor 12-3 (36★)
  Hu Tao Lv.90/90 C1
  Raiden Shogun Lv.90/90 C2
*/
```

--------------------------------

### EnkaClient#fetchCollapsedUser

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Fetches a fast profile overview without detailed character builds.

```APIDOC
## EnkaClient#fetchCollapsedUser

### Description
Returns a `GenshinUser` object, providing a fast profile overview without character details or `avatarInfoList`. This method is significantly faster than `fetchUser` and is suitable for displaying player cards or profile summaries.

### Method
```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

(async () => {
    const user = await enka.fetchCollapsedUser(825436941);

    console.log(`${user.nickname} | World Level ${user.worldLevel}`);
    console.log(`Characters on showcase:`);
    for (const preview of user.charactersPreview) {
        console.log(`  ${preview.costume.characterData.name.get()} Lv.${preview.level} (${preview.element?.name.get() ?? "?"}) C${preview.constellation ?? "?"}`);
    }
    enka.close();
})();
```

### Parameters
#### Path Parameters
- **uid** (number) - Required - The in-game UID of the player.

### Response
#### Success Response (200)
- **GenshinUser** - An object containing a collapsed view of the player's profile.

### Response Example
```json
{
  "nickname": "yuko1101",
  "worldLevel": 8,
  "charactersPreview": [
    {
      "costume": {
        "characterData": {
          "name": {
            "en": "Hu Tao"
          }
        }
      },
      "level": 90,
      "element": {
        "name": {
          "en": "Pyro"
        }
      },
      "constellation": 1
    },
    {
      "costume": {
        "characterData": {
          "name": {
            "en": "Raiden Shogun"
          }
        }
      },
      "level": 90,
      "element": {
        "name": {
          "en": "Electro"
        }
      },
      "constellation": 2
    }
  ]
}
```
```

--------------------------------

### ElementalBurst#getSkillAttributes

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Resolves in-game ability values for a character's Elemental Burst at a given skill level.

```APIDOC
## ElementalBurst#getSkillAttributes — Elemental Burst skill attributes

### Description
Reads a live character's skill levels and uses `ElementalBurst#getSkillAttributes` to resolve in-game ability values at a given level.

### Method Signature
`elementalBurst.getSkillAttributes(level: number): Array<Attribute>

### Parameters
* **level** (number) - Required - The skill level (up to 10 or 15 depending on talents) for which to retrieve attributes.

### Response
* **Array<Attribute>** - An array of skill attributes.
  * **getAttributeData(language: string): AttributeData** - Retrieves attribute data for a specific language.
    * **name** (string) - The name of the attribute.
    * **valueText** (string) - The formatted value of the attribute.
```

--------------------------------

### Fetch All and Specific Weapon Data

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Retrieves a list of all available weapons or data for a specific weapon by its ID. Includes details on name, stars, type, refinements, and stats at a given level and ascension. Requires EnkaClient.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// All weapons (filters invalid entries and non-codex weapons by default)
const weapons = enka.getAllWeapons();
console.log(`Total weapons: ${weapons.length}`);

// A specific weapon
const staffOfHoma = enka.getWeaponById(13501);
console.log(staffOfHoma.name.get("en"));             // "Staff of Homa"
console.log(`${staffOfHoma.stars}★ ${staffOfHoma.weaponType}`);

// Refinement descriptions
for (const ref of staffOfHoma.refinements) {
    console.log(`R${ref.level + 1}: ${ref.description.get("en")}`);
}

// Stats at ascension 6, level 90
const stats = staffOfHoma.getStats(6, 90);
for (const stat of stats) {
    console.log(`${stat.fightPropName.get()}: ${stat.valueText}`);
}
// Base ATK: 608 | HP%: 66.2%
```

--------------------------------

### EnkaClient#getAllCostumes

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Lists all character costumes (skins), with an option to include or exclude default costumes.

```APIDOC
## EnkaClient#getAllCostumes — costume (skin) data

Lists all character costumes, with optional inclusion of default costumes.

### Method
- `getAllCostumes(includeDefault: boolean)`: Lists all costumes, with `includeDefault` determining if default costumes are included.

### Example Usage
```js
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient({ defaultLanguage: "en" });

// Non-default (premium) costumes only
const premiumCostumes = enka.getAllCostumes(false);
for (const costume of premiumCostumes) {
    const char = costume.getCharacterData();
    console.log(`${char.name.get("en")} — ${costume.name.get("en")}`);
    console.log(`  Icon: ${costume.icon.url}`);
}
// Kamisato Ayaka — Springbloom Missive
// Jean — Sea Breeze Dandelion
// …
```
```

--------------------------------

### Fetch Player Data by User ID

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Retrieve a user's Genshin Impact data using their user ID. Requires an initialized EnkaClient instance.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

enka.fetchUser(825436941).then(user => {
  console.log(user);
});

```

--------------------------------

### Resolve Image Assets with EnkaClient

Source: https://context7.com/yuko1101/enka-network-api/llms.txt

Use EnkaClient to resolve image URLs for characters and weapons. Supports custom CDN priorities by providing an array of base URLs with priority, format, and regex matching.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

const ganyu = enka.getCharacterById(10000037);
console.log(ganyu.icon.url);         // CDN URL for character icon
console.log(ganyu.splashImage.url);  // Splash/gacha art URL
console.log(ganyu.cardIcon.url);     // Card-style icon URL
console.log(ganyu.sideIcon.url);     // Side portrait icon URL

const homa = enka.getWeaponById(13501);
console.log(homa.icon.url);          // Weapon icon
console.log(homa.awakenIcon.url);    // Ascended weapon icon
console.log(homa.splashImage.url);   // Weapon gacha splash
```

```javascript
// Custom CDN priority (added at the front, overrides defaults)
const enkaCustom = new EnkaClient({
    imageBaseUrls: [
        {
            url: "https://my-own-cdn.example.com/gi",
            priority: 20,
            format: "PNG",
            regexList: [/.*/],
        },
    ],
});
const ganyu2 = enkaCustom.getCharacterById(10000037);
console.log(ganyu2.icon.url); // resolves from custom CDN if regex matches
```

--------------------------------

### Activate Auto Cache Updater

Source: https://github.com/yuko1101/enka-network-api/blob/main/README.md

Enable automatic updates for Genshin cache data with configurable intervals and callbacks for update events. It's recommended to move the cache directory under your project folder when using this feature.

```javascript
const { EnkaClient } = require("enka-network-api");
const enka = new EnkaClient();

enka.cachedAssetsManager.activateAutoCacheUpdater({
    instant: true, // Run the first update check immediately
    timeout: 60 * 60 * 1000, // 1 hour interval
    onUpdateStart: async () => {
        console.log("Updating Genshin Data...");
    },
    onUpdateEnd: async () => {
        enka.cachedAssetsManager.refreshAllData(); // Refresh memory
        console.log("Updating Completed!");
    }
});

// // deactivate
// enka.cachedAssetsManager.deactivateAutoCacheUpdater();

```