starrail.js

</> Documentation | ⚙ NPM | GitHub

About

A Node.js Enka.Network API wrapper for Honkai: Star Rail.

Features

User Data and Character Stats by UID with Enka.Network API (or with MiHoMo API).
All Characters and All Light Cones Data.
Cache Updater for the new update of Honkai: Star Rail. (Update characters and light cones immediately.)

Installation

Node.js 16 or newer is required.

Install starrail.js including Star Rail cache data.

npm install starrail.js@latest

Install using ghproxy.com

npm install starrail.js@latest --sr-ghproxy=true

If you have already moved the cache to another folder, you can also install without downloading the cache.

npm install starrail.js@latest --sr-nocache=true

About Star Rail Cache Data

Star Rail cache data is from Dimbreath/StarRailData

This data contains data of characters, light cones, materials, and more structure information of Star Rail.

You can change your cache directory.

const { StarRail } = require("starrail.js");

// Change the directory to store cache data.
// Default directory is node_modules/starrail.js/cache.
const client = new StarRail();
client.cachedAssetsManager.cacheDirectoryPath = "./cache";
client.cachedAssetsManager.cacheDirectorySetup();

// OR

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

Updating

You can update your Star Rail cache data.

const { StarRail } = require("starrail.js");
const client = new StarRail({ showFetchCacheLog: true }); // showFetchCacheLog is true by default

client.cachedAssetsManager.fetchAllContents(); // returns promise

Also, you can activate auto cache updater.

When using the auto-cache updater, we recommend moving the cache directory directly under your project folder.

const { StarRail } = require("starrail.js");
const client = new StarRail();

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

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

Where is the image file for ImageAssets?

As far as I know, there are few cdns for starrail. So, this library cannot provide urls of some images and ImageAssets#url is often unavailable. But you can extract image files from StarRail Game Data with HoyoStudio or something else.

If you would like ImageAssets#url to show the paths to your extracted images, you can use imageBaseUrls option.

const { StarRail } = require("starrail.js");
const client = new StarRail();

client.options.imageBaseUrls.push(
    {
        regexList: [/.*/], // for all images
        /*  
          "LOWER_CASE" if the names of folders in your extracted directory are in lowercase. e.g. "spriteoutput/itemicon/relicicons/IconRelic_101_1.png"
          "UPPER_CAMEL_CASE" if the names of folders in your extracted directory are in upper camel case. e.g. "SpriteOutput/ItemIcon/RelicIcons/IconRelic_101_1.png"
          "NONE" if your extracted files are not grouped in folders. e.g. "IconRelic_101_1.png"
        */
        filePath: "LOWER_CASE",
        priority: 10,
        url: "Your directory path to assets/asbres", // path to directory of extracted files
    }
);

How to use

Fetching Player Data

StarRail#fetchUser

const { StarRail } = require("starrail.js");
const client = new StarRail();

client.fetchUser(800069903).then(user => {
  console.log(user);
});

Star Rail Character List

StarRail#getAllCharacters

const { StarRail } = require("starrail.js");
const client = new StarRail();

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

Star Rail Light Cone List

StarRail#getAllLightCones

const { StarRail } = require("starrail.js");
const client = new StarRail();

const lightCones = client.getAllLightCones();
// print light cone names in language "jp"
console.log(lightCones.map(w => w.name.get("jp")));

More examples are available in example folder.

For more information, please check Documentation.

You can see the changelog here.

Index

Functions

Interfaces

Type Aliases

Variables

Type Aliases

CombatTypeId

CombatTypeId	In-game Name
Physical	Physical
Fire	Fire
Ice	Ice
Thunder	Lightning
Wind	Wind
Quantum	Quantum
Imaginary	Imaginary

EffectType

LanguageCode

LanguageCode: chs | cht | de | en | es | fr | id | jp | kr | pt | ru | th | vi

LanguageMap

LanguageMap: { [ key in LanguageCode ]: {} }

NullableLanguageMap

NullableLanguageMap: { [ key in LanguageCode ]: {} | null }

OtherStatPropertyType

OtherStatPropertyType: keyof typeof otherStatPropertyTypes

StatPropertyTypes which do not exist in AvatarPropertyConfig.json

OtherStatPropertyType	isPercent	defaultValue	Comment
SpeedAddedRatio	true	0

Overwrite

Overwrite<T, U>: Omit<T, keyof U> & U

Type parameters

T
U: { [ Key in keyof T ]?: unknown }

PathId

PathId	In-game Name
Warrior	Destruction
Rogue	The Hunt
Mage	Erudition
Shaman	Harmony
Warlock	Nihility
Knight	Preservation
Priest	Abundance

Platform

Platform: PC | ANDROID | IOS | PS5

RelicTypeId

RelicTypeId	In-game Name
HEAD	Head
HAND	Hands
BODY	Body
FOOT	Feet
OBJECT	Link Rope
NECK	Planar Sphere

SimpleMap

SimpleMap<K, V>: Map<K, SimpleMap<K, V> | V>

Type parameters

SimpleObject

SimpleObject<T>: {}

Type parameters

T = never

Type declaration

[key string]: SimpleObject<T> | T

SkillType

StatPropertyType

StatPropertyType: keyof typeof statPropertyTypes

StatPropertyType	isPercent	defaultValue	Comment
MaxHP	false	0
Attack	false	0
Defence	false	0
Speed	false	0
CriticalChance	true	0	unknown, but used, likely percent
CriticalDamage	true	0	unknown, but used, likely percent
BreakDamageAddedRatio	true	0	unknown, not used, likely percent
BreakDamageAddedRatioBase	true	0
HealRatio	true	0	unknown, not used, likely percent
MaxSP	false	0
SPRatio	true	0	unknown, not used, likely percent
StatusProbability	true	0	unknown, only used in inventory sort, likely percent
StatusResistance	true	0	unknown, only used in inventory sort, likely percent
CriticalChanceBase	true	0
CriticalDamageBase	true	0
HealRatioBase	true	0
StanceBreakAddedRatio	true	0	unknown, not used, likely percent
SPRatioBase	true	1
StatusProbabilityBase	true	0
StatusResistanceBase	true	0
PhysicalAddedRatio	true	0
PhysicalResistance	true	0
FireAddedRatio	true	0
FireResistance	true	0
IceAddedRatio	true	0
IceResistance	true	0
ThunderAddedRatio	true	0
ThunderResistance	true	0
WindAddedRatio	true	0
WindResistance	true	0
QuantumAddedRatio	true	0
QuantumResistance	true	0
ImaginaryAddedRatio	true	0
ImaginaryResistance	true	0
BaseHP	false	0
HPDelta	false	0
HPAddedRatio	true	0
BaseAttack	false	0
AttackDelta	false	0
AttackAddedRatio	true	0
BaseDefence	false	0
DefenceDelta	false	0
DefenceAddedRatio	true	0
BaseSpeed	false	0
HealTakenRatio	true	0	unknown, not used, likely percent
PhysicalResistanceDelta	false	0	unknown, not used, likely flat
FireResistanceDelta	false	0	unknown, not used, likely flat
IceResistanceDelta	false	0	unknown, not used, likely flat
ThunderResistanceDelta	false	0	unknown, not used, likely flat
WindResistanceDelta	false	0	unknown, not used, likely flat
QuantumResistanceDelta	false	0	unknown, not used, likely flat
ImaginaryResistanceDelta	false	0	unknown, not used, likely flat
SpeedDelta	false	0

Variables

constcombatTypeIconColors

combatTypeIconColors: { [ key in CombatTypeId ]: number } = ...

constdefaultClientOption

defaultClientOption: Overwrite<ClientOptions, { enkaSystem: EnkaSystem | null }> = ...

constotherStatPropertyTypes

otherStatPropertyTypes: { SpeedAddedRatio: { defaultValue: 0; isPercent: true } } = ...

Type declaration

readonlySpeedAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true

constpathMap

pathMap: { Knight: Preservation; Mage: Erudition; Priest: Abundance; Rogue: The Hunt; Shaman: Harmony; Unknown: General; Warlock: Nihility; Warrior: Destruction } = ...

Type declaration

readonlyKnight: Preservation
readonlyMage: Erudition
readonlyPriest: Abundance
readonlyRogue: The Hunt
readonlyShaman: Harmony
readonlyUnknown: General
readonlyWarlock: Nihility
readonlyWarrior: Destruction

conststatPropertyTypes

statPropertyTypes: { Attack: { defaultValue: 0; isPercent: false }; AttackAddedRatio: { defaultValue: 0; isPercent: true }; AttackDelta: { defaultValue: 0; isPercent: false }; BaseAttack: { defaultValue: 0; isPercent: false }; BaseDefence: { defaultValue: 0; isPercent: false }; BaseHP: { defaultValue: 0; isPercent: false }; BaseSpeed: { defaultValue: 0; isPercent: false }; BreakDamageAddedRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }; BreakDamageAddedRatioBase: { defaultValue: 0; isPercent: true }; CriticalChance: { comment: unknown, but used, likely percent; defaultValue: 0; isPercent: true }; CriticalChanceBase: { defaultValue: 0; isPercent: true }; CriticalDamage: { comment: unknown, but used, likely percent; defaultValue: 0; isPercent: true }; CriticalDamageBase: { defaultValue: 0; isPercent: true }; Defence: { defaultValue: 0; isPercent: false }; DefenceAddedRatio: { defaultValue: 0; isPercent: true }; DefenceDelta: { defaultValue: 0; isPercent: false }; FireAddedRatio: { defaultValue: 0; isPercent: true }; FireResistance: { defaultValue: 0; isPercent: true }; FireResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; HPAddedRatio: { defaultValue: 0; isPercent: true }; HPDelta: { defaultValue: 0; isPercent: false }; HealRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }; HealRatioBase: { defaultValue: 0; isPercent: true }; HealTakenRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }; IceAddedRatio: { defaultValue: 0; isPercent: true }; IceResistance: { defaultValue: 0; isPercent: true }; IceResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; ImaginaryAddedRatio: { defaultValue: 0; isPercent: true }; ImaginaryResistance: { defaultValue: 0; isPercent: true }; ImaginaryResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; MaxHP: { defaultValue: 0; isPercent: false }; MaxSP: { defaultValue: 0; isPercent: false }; PhysicalAddedRatio: { defaultValue: 0; isPercent: true }; PhysicalResistance: { defaultValue: 0; isPercent: true }; PhysicalResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; QuantumAddedRatio: { defaultValue: 0; isPercent: true }; QuantumResistance: { defaultValue: 0; isPercent: true }; QuantumResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; SPRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }; SPRatioBase: { defaultValue: 1; isPercent: true }; Speed: { defaultValue: 0; isPercent: false }; SpeedDelta: { defaultValue: 0; isPercent: false }; StanceBreakAddedRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }; StatusProbability: { comment: unknown, only used in inventory sort, likely percent; defaultValue: 0; isPercent: true }; StatusProbabilityBase: { defaultValue: 0; isPercent: true }; StatusResistance: { comment: unknown, only used in inventory sort, likely percent; defaultValue: 0; isPercent: true }; StatusResistanceBase: { defaultValue: 0; isPercent: true }; ThunderAddedRatio: { defaultValue: 0; isPercent: true }; ThunderResistance: { defaultValue: 0; isPercent: true }; ThunderResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }; WindAddedRatio: { defaultValue: 0; isPercent: true }; WindResistance: { defaultValue: 0; isPercent: true }; WindResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false } } = ...

Type declaration

readonlyAttack: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyAttackAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyAttackDelta: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyBaseAttack: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyBaseDefence: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyBaseHP: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyBaseSpeed: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyBreakDamageAddedRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, not used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyBreakDamageAddedRatioBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyCriticalChance: { comment: unknown, but used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, but used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyCriticalChanceBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyCriticalDamage: { comment: unknown, but used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, but used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyCriticalDamageBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyDefence: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyDefenceAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyDefenceDelta: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyFireAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyFireResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyFireResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyHPAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyHPDelta: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyHealRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, not used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyHealRatioBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyHealTakenRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, not used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyIceAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyIceResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyIceResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyImaginaryAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyImaginaryResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyImaginaryResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyMaxHP: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyMaxSP: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyPhysicalAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyPhysicalResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyPhysicalResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyQuantumAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyQuantumResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyQuantumResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlySPRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, not used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlySPRatioBase: { defaultValue: 1; isPercent: true }
- readonlydefaultValue: 1
- readonlyisPercent: true
readonlySpeed: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlySpeedDelta: { defaultValue: 0; isPercent: false }
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyStanceBreakAddedRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, not used, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyStatusProbability: { comment: unknown, only used in inventory sort, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, only used in inventory sort, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyStatusProbabilityBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyStatusResistance: { comment: unknown, only used in inventory sort, likely percent; defaultValue: 0; isPercent: true }
- readonlycomment: unknown, only used in inventory sort, likely percent
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyStatusResistanceBase: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyThunderAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyThunderResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyThunderResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false
readonlyWindAddedRatio: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyWindResistance: { defaultValue: 0; isPercent: true }
- readonlydefaultValue: 0
- readonlyisPercent: true
readonlyWindResistanceDelta: { comment: unknown, not used, likely flat; defaultValue: 0; isPercent: false }
- readonlycomment: unknown, not used, likely flat
- readonlydefaultValue: 0
- readonlyisPercent: false

About​

Features​

Installation​

About Star Rail Cache Data​

Updating​

Where is the image file for ImageAssets?

How to use

Fetching Player Data​

Star Rail Character List​

Star Rail Light Cone List​

Index

Classes

Functions

Interfaces

Type Aliases

Variables

Type Aliases

CombatTypeId

EffectType

LanguageCode

LanguageMap

NullableLanguageMap

OtherStatPropertyType

Overwrite

Type parameters

PathId

Platform

RelicTypeId

SimpleMap

Type parameters

SimpleObject

Type parameters

Type declaration

[key string]: SimpleObject<T> | T

SkillType

StatPropertyType

Variables

constcombatTypeIconColors

constdefaultClientOption

constotherStatPropertyTypes

Type declaration

readonlySpeedAddedRatio: { defaultValue: 0; isPercent: true }

readonlydefaultValue: 0

readonlyisPercent: true

constpathMap

Type declaration

readonlyKnight: Preservation

readonlyMage: Erudition

readonlyPriest: Abundance

readonlyRogue: The Hunt

readonlyShaman: Harmony

readonlyUnknown: General

readonlyWarlock: Nihility

readonlyWarrior: Destruction

conststatPropertyTypes

Type declaration

readonlyAttack: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyAttackAddedRatio: { defaultValue: 0; isPercent: true }

readonlydefaultValue: 0

readonlyisPercent: true

readonlyAttackDelta: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyBaseAttack: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyBaseDefence: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyBaseHP: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyBaseSpeed: { defaultValue: 0; isPercent: false }

readonlydefaultValue: 0

readonlyisPercent: false

readonlyBreakDamageAddedRatio: { comment: unknown, not used, likely percent; defaultValue: 0; isPercent: true }

readonlycomment: unknown, not used, likely percent

readonlydefaultValue: 0

About

Features

Installation

About Star Rail Cache Data

Updating

Fetching Player Data

Star Rail Character List

Star Rail Light Cone List