whiteout-survival-data

⚠️ Work in progress. This package has not had a first release yet. The data is still being collected, so some of it is missing or not 100% complete, some fields are placeholders, and some values may be wrong. The API can also change without notice. If you have data that is missing, you are welcome to share it through an issue or a pull request (see Contributing). Otherwise, please wait while the data is gathered. Treat everything here as unstable until the first tagged release. See Known Gaps for what is missing.

Installation

The package needs Node 24 or later.

npm install whiteout-survival-data
# or
pnpm add whiteout-survival-data

Quick Start

Every module exports a factory function that returns a chainable query builder.

import { buildings } from "whiteout-survival-data";

const furnace = buildings().findByName("Furnace");
furnace?.levels.find((l) => l.label === "FC 10");

How It Works

All standard modules follow the same query builder pattern built on a shared QueryBase<T> class:

factory() // Start with all data
  .filterMethod() // Chain filters (returns new query)
  .sortMethod() // Chain sorts (returns new query)
  .terminalMethod(); // Get results

Terminal Methods

Every query builder provides these 6 terminal methods:

| Method | Returns | Description | | ------------------- | ---------------- | ------------------------------------- | | .get() | T[] | All results as an array | | .first() | T \| undefined | First result | | .find(id) | T \| undefined | Find by exact ID | | .findByName(name) | T \| undefined | Find by name (case-insensitive) | | .search(query) | T[] | Partial name match (case-insensitive) | | .count() | number | Number of results |

Modules

Each module has its own README with usage examples, the query methods, the shape of the data, and notes on where the data came from. The counts below are the number of entries each factory returns.

Buildings and city

| Factory | Entries | Description | Details | | ------------------------- | ------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- | | buildings() | 27 | Every building with its per-level cost, build time, power, and requirements | README | | facilities() | 9 | Buildings that have no upgrade levels | README | | fireCrystalTable() | 8 | Fire Crystals and Refined Fire Crystals each building needs for FC 1 to FC 10 | README | | fireCrystalLevels() | 10 | FC 1 to FC 10 level badge icons | README | | fireCrystalShardTable() | 9 | Fire Crystal Shards and Refined Fire Crystals for T11 and T12 troop research | README | | lumberCamp() | 10 | Daybreak Island Lumber Camp upgrade table | README | | treeOfLife() | 10 | Daybreak Island Tree of Life upgrade table | README | | decoration() | 104 | Daybreak Island decorations | README |

Heroes and experts

| Factory | Entries | Description | Details | | -------------------------- | ------- | ------------------------------------------------------------------------------- | --------------------------------------------------------- | | heroes() | 65 | Heroes with stats, skills, shard costs, levels, and exclusive weapons | README | | heroWidgets() | 10 | Widgets that each exclusive weapon level costs | README | | heroGearEnhancement() | 100 | Hero gear enhancement levels 1 to 100 | README | | heroGearEmpowerment() | 100 | Hero gear empowerment levels 1 to 100 | README | | heroGearMasteryForging() | 84 | Hero gear mastery forging rows | README | | heroGearSlots() | 4 | The four Hero Gear slots with an icon for each troop type | README | | heroGearStats() | 12 | Hero gear stats per slot, troop type, and level | README | | experts() | 11 | Dawn Academy experts with skills, talents, and affinity levels | README | | expertRelationships() | 11 | Expert relationship statuses by affinity level | README | | unreleasedExperts() | 0 | Experts that are announced and not released: name, icon, and unlock requirement | README | | pets() | 14 | Beast Cage pets with skills and level tables | README |

Gear, troops, and research

| Factory | Entries | Description | Details | | ----------------------- | ------- | -------------------------------------------------------------------- | ----------------------------------------------------- | | chiefGearSlots() | 6 | Chief Gear equip slots | README | | chiefGear() | 150 | Chief Gear upgrade table | README | | chiefGearSetBonuses() | 14 | The set bonus of each Chief Gear tier, with chiefGearSetBonus() | README | | chiefCharmSlots() | 3 | Chief Charm slots by troop type | README | | chiefCharm() | 75 | Chief Charm upgrade table | README | | chiefGearConverter() | 7 | Chief Gear material exchange rates | README | | chiefCharmConverter() | 4 | Chief Charm material exchange rates | README | | troops() | 3 | Troop tiers with cost, training time, power, and unlock requirements | README | | research() | 290 | Research Center tech tree | README | | researchTree() | 7 | Positions and links of the Research tech tree tabs | README |

Alliance

| Factory | Entries | Description | Details | | -------------------- | ------- | ------------------------------------- | -------------------------------------------------- | | allianceBanner() | 37 | Alliance territory banner build costs | README | | allianceTech() | 59 | Alliance technology tree | README | | allianceFacility() | 8 | Map-based alliance facilities | README | | allianceFortress() | 17 | Castle, strongholds, and fortresses | README | | alliancePrestige() | 6 | Prestige buildings and their bonuses | README |

Events, items, and account

| Factory | Entries | Description | Details | | -------------------------- | ------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | events() | 65 | Game events with scoring, rewards, and tips | README | | eventBuff() | 14 | Buff sources that apply in each game mode | README | | items() | 418 | Item catalog with icons and sources | README | | skins() | 223 | Cosmetic skins | README | | serverTimeline() | 33 | Server age timeline of unlocks, with serverAge() and serverTimelineStatus() | README | | chiefOrders() | 9 | The Chief Orders, with the three that replace others at Fire Crystal 1 | README | | castleAppointments() | 8 | Castle positions and the buffs they give | README | | presidentSkills() | 9 | The President's skills: global perks, Receive Tribute, and the skills that act on a Chief | README | | dailies() | 15 | Default daily tasks: the steps of a daily routine | README | | dailyMissions() | 21 | The in-game Daily Missions, with the task and rewards of each, and the activeness | README | | collectionRewardLevels() | 51 | The collection levels, with the medallion and the rewards of each, and the medallion buffs | README | | tundraAlbum() | 14 | Tundra Album albums, with the puzzles, pieces, rewards, and buff of each | README | | vip() | 12 | VIP 1 to 12 progression | README | | vipSignInRewards() | 5 | VIP points of the daily sign-in by streak day, with vipSignInPoints() | README |

Calculators

The calculators are plain functions built on the modules above. Each takes a goal object and returns the resources, time, power, and event points for the plan. The calculators overview explains the shared conventions, and each calculator has its own guide.

| Function | What it calculates | Details | | ----------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- | | calculateSvs() | State of Power score by day, phase, and event | Guide | | calculateBuffs() | Speed boosts and other buffs by stat, with every source | Guide | | calculateBeasts() | Beasts or Polar Terrors that stamina pays for, with event points | Guide | | calculateAllianceShowdown() | Alliance Showdown score, with the Dawn Hymn bonus | Guide | | calculateKingOfIcefield() | King of Icefield score | Guide | | calculateHallOfChief() | Hall of Chief score | Guide | | calculateChiefGear() | Materials, score, power, and event points for Chief Gear upgrades | Guide | | calculateChiefCharm() | Materials, score, power, and event points for Chief Charm upgrades | Guide | | calculateTroops() | Troops, resources, and time for training and promotion | Guide | | calculateResearch() | Resources, time, and power for research goals | Guide | | calculatePets() | Pet food, items, stat gains, and event points for leveling pets | Guide | | calculateExperts() | Books of Knowledge, sigils, EXP, and affinity for experts | Guide | | calculateBuildings() | Resources, time, power, and event points for building upgrades | Guide | | calculateHeroGear() | Resources, power, stats, and event points for one hero gear piece | Guide | | calculateHeroUpgrade() | Shards, skill manuals, and Widgets for one hero | Guide |

Raw Data Access

JSON data files can be imported directly, without importing the JS/TS package:

import buildings from "whiteout-survival-data/data/chief/buildings.json";

Change Log

Check out the Change Log for new breaking changes, features, and bug fixes per release of a new version.

Known Gaps

This is what the data does not hold yet. Each module README gives the detail.

• Events. 15 of the 65 events have no schedule. Only 1 of the 9 expert extra tier thresholds is known. The Hall of Chief ranking lists only the first ranks, and its hero shard rewards have no amount. See Events.
• Heroes. The 36 heroes of Generations 6 to 17 have a level power of 0 at every level, and the 39 heroes of Generations 5 to 17 have a shard power of 0. Stars 4 and 5 of Generation 5 are not read. The Talent of Jeronimo and Natalia has no star requirement and no power gain. See Heroes.
• Experts. Justus has no stat bonus or power on his affinity levels, no power on his skills, and no skill icons. The buff calculator rejects his affinity. See Experts.
• Items. 28 items have no icon: the shared Blueprint and the furniture of the six entertainment buildings other than the Farm, the Climbing Gym, and the Yoga Studio. See Items.
• Skins. The 32 newest skins have no img. See Skins.
• Buildings. The nine entertainment buildings have no img. See Buildings.
• Alliance prestige buildings. The tiers of five of the six buildings are numbered, because their names are not known, and the cost to build one is not stored. See Alliance Prestige Buildings.
• Tundra Album. Only 14 of the 16 albums are in. See Tundra Album.
• Daily tasks. The missions in dailyMissions() have only the levels known so far, and the daily reset time is not stored. See Daily Missions and Dailies.
• Pets. Only the maximum refinement percent of each pet is stored. The steps and the quality ranges are not. See Pets.

If you have any of this data, see Contributing.

Contributing

Bug Reports, Feature Requests, and Pull Requests are welcome on GitHub at https://github.com/chiefpansancolt/whiteout-survival-data. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To see more about Contributing check out this document.

1. Fork Repo and create new branch
2. Once all is changed and committed create a pull request.
3. Ensure all merge conflicts are fixed and CI is passing.

Development

See CONTRIBUTING.md for setup instructions and DEVELOPMENT.md for the full guide on adding new modules.

pnpm install         # Install dependencies
pnpm build           # Build with tsup
pnpm test:coverage   # Run tests with the 100% coverage gate
pnpm lint            # Type-check + ESLint
pnpm format          # Format with Prettier
pnpm sample          # Exercise queries end to end

Support the Project

If you find this project helpful, consider supporting its development:

License

whiteout-survival-data is available as open source under the terms of the MIT License.

Disclaimer

This project is not affiliated with, endorsed by, or connected to Whiteout Survival or Century Games. Game images and names are used for reference purposes only.