Data repository for SkyGame-Planner.
npm install skygame-data
A fan-made data repository for Sky: Children of the Light. This project contains the raw data that fuels SkyGame-Planner. The data has been separated to make it easier to consume in other projects. Do note that various bits of data are tightly coupled to the Sky Planner, such as links to image assets contained in that project.
The data is published as an NPM package together with some useful scripts to parse the data.
https://www.npmjs.com/package/skygame-data
To make sure the format of data doesn't change unexpectedly, this project follows Semantic Versioning.
* Major versions are incremented when the structure of assets classified as "stable" changes.
* Minor versions are incremented when backward-compatible changes are made to the data, or when assets classified as "unstable" are changed.
* Patch versions are incremented when data is added or changed without any structural changes to the project.
Files from the package can be accessed directly through CDN options such as unpkg. Version wildcards can be used.
Below are some examples for the everything.json file.
| Version | Link |
|---------|------|
| Latest |
| Latest within major 1 |
| Latest within minor 1.0 |
| Version 1.0.0 |
Stable (see versioning)
``
realms, areas, winged-lights, map-shrines, constellations,
seasons, events, event-instances, event-instance-spirits,
spirits, spirit-trees, spirit-tree-tiers, nodes,
traveling-spirits, returning-spirits,
items, item-lists, shops, iaps
Unstable
`
candles
The project uses nanoids of length 10 as GUIDs. When an entity is referenced, its GUID is used in place of the full JSON object. This mechanism can be compared to a foreign key in a database.
Example
In /assets/event-instance-spirits.json, you'll find various references to spirits:
`jsonc`
{ "guid": "ACtiGG4_cq", "spirit": "TgUgZjfoMI", "tree": "EUQHt6adrz" }
* guid: Unique GUID of this specific JSON object.spirit
* : GUID reference to the spirit found in /assets/spirits.json.tree
* : GUID reference to the spirit tree found in /assets/spirit-trees.json.
In the /src/assets folder, the data is organized in folders to make it easier to manage within this repository. /assets
In the package, the contents of these folders are compiled into minified JSON files located at .
Data in these files is stored as a JSON object formatted { "items": [ ... ] }.
Example
/src/assets/events/** --> node_modules/skygame-data/assets/events.json /src/assets/events/** -->
Everything
/assets/everything.json contains all data in a single file.
Data in this file is stored as a JSON object formatted as below.
`jsonc`
{
"realms": { "items": [ /.../ ] },
"areas": { "items": [ /.../ ] },
// ...
}
> [!TIP]
> It is recommended to use the GUIDs whenever possible.
All items (/assets/items.json) have a unique numeric ID on top of the GUID. This number is used by the Sky Planner in various places, such as encoding a selection of items with Base36 to a fixed length of 3 characters to keep URLs shorter.
Example
`
https://sky-planner.com/item/unlock-calculator?items=00a00g
00a --> parseInt('00a', 36) --> ID 10 --> Pointing Candlemaker Hair
00g --> parseInt('00g', 36) --> ID 16 --> Pointing Candlemaker Outfit
Dates are stored in the format YYYY-MM-DD. Sky: Children of the Light uses the America/Los_Angeles timezone for the daily reset, so this timezone should be respected when calculating the actual time an event begins or ends.
The following diagram illustrates which references exist between the data.
References marked in bold are stored as GUID reference in the data. For one-to-many relations, an array of GUIDs is used. If no reference exists, the key is omitted from the data.
Circular references are marked in italic and are created automatically when parsing the data using the included Scripts.
The project includes some utilities to parse the data into a Javascript object with resolved GUID references. Do note that this data can not be serialized normally due to the circular references in the data, as per the diagram.
SkyDataResolver
Helper class that can parse and resolve references using the everything.json file.
Example:
`ts
import { SkyDataResolver } from 'skygame-data';
(async () => {
const response = await fetch('https://unpkg.com/skygame-data@0.2.0/assets/everything.json');
const data = await response.json();
const resolved = await SkyDataResolver.resolve(data);
console.log(resolved.seasons.items.length);
})();
`
SkyDateHelper
Helper class that can parse date strings to Luxon DateTime objects based on the America/Los_Angeles timezone.
Example:
`ts
import { SkyDateHelper } from 'skygame-data';
const date = SkyDateHelper.fromStringSky('2026-01-01');
console.log(date.toISO()); // 2026-01-01T08:00:00.000Z
`
SpiritTreeHelper
Helper class that has some utilities for working with spirit trees.
Example:
`ts
import { SpiritTreeHelper } from 'skygame-data';
const resolved; // See SkyDataResolver example.
const spirit = resolved.spirits.items.find(s => s.name === 'Migrating Bellmaker')!;
const nodes = SpiritTreeHelper.getNodes(spirit.tree!);
console.log(nodes.length);
`
NodeHelper
Helper class that has some utilities for working with nodes.
Example:
`ts
import { NodeHelper } from 'skygame-data';
const resolved; // See SkyDataResolver example.
const item = resolved.items.items.find(i => i.name === 'Admiring Actor Outfit')!;
const node = item.nodes!.at(0);
const nodes = NodeHelper.trace(node);
console.log(nodes.length);
``
If you are or want to be actively involved with this project, feel free to join our Discord:
http://discord.gg/qjumJY7MKD
The data isn't accurate, how can I help?
Since Sky: Children of Light is a live service game with frequent updates, keeping the data up to date and accurate is an ongoing effort.
Simply opening issues or informing us on our Discord is a good way to help.
Contributions through pull requests are welcome and very much appreciated.
Why JSON files?
The main goal of this project is to provide the data in an accessible and serverless format. This allows projects such as the Sky Planner to be hosted with static assets and not rely on a back-end for fetching data.