@r0cksolid/emerald-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 R0ck Solid Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @r0cksolid/emerald-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A library of Hypixel SkyBlock items, with a snapshot of the game's data built in. It answers how to get an item, what making it takes, what drops it, and what an item's lore says, from synchronous lookups over a catalog loaded once.
+
+## What it answers
+
+- **Lookups.** An `ItemCatalog` holds every item record, recipe, NPC offer and trade, mob drop, attribute shard and collection item in the snapshot. `item`, `summaryOf`, `recipesFor`, `usesOf`, `offersBy`, `dropSourcesFor`, `dropsOf`, `shardOf` and `collectionOf` look them up by id. An unknown id answers `undefined` or an empty list.
+- **Search.** `catalog.search(query, limit, offset, filter?)` ranks items by name or id, tolerates typos, and groups pets, minions and enchanted books into one row per family. A variant word picks a member: `leg bee` targets the Legendary Bee.
+- **Ways to get an item.** `itemWays(catalog, id)` sorts every way to get an item into Obtain (activities, buying, opening containers) and Make (crafting, forging, Kat, shard fusion, the Enchantment Table), tagged with upgrades and the events or mayor perks that gate them. `listWays` flattens the answer.
+- **Plans.** `itemPlan(catalog, id, count)` expands an item into the steps that make it, inputs first, the materials those steps stop at, and the total coins, currencies and station time.
+- **Item details.** `itemDetails` reads lore into a type, stats, tags and text blocks. `itemGlyphs` picks the game-font glyphs a page needs to draw it, and `petValueAt` fills in a pet's values at a level.
+
+The records and answers have TypeBox JSON Schemas beside their types, such as `ItemPlanSchema`, `ItemWaysSchema` and `SearchPageSchema`, for checking them or describing them in an API contract.
+
+## Install
+
+```sh
+npm install @r0cksolid/emerald-core
+```
+
+The package is ESM only and ships type declarations. It has two entries:
+
+- `@r0cksolid/emerald-core`, the main entry: the catalog, every query, the schemas and their types. It imports nothing from Node, so it runs in any JavaScript runtime.
+- `@r0cksolid/emerald-core/loader`: `loadItemCatalog`, which reads a snapshot from disk, and `committedDataDirectory`, which finds the snapshot this package ships. It needs Node.
+
+## Load the snapshot
+
+The package ships its snapshot in `data/`: `snapshot.json` holds the records, and `snapshot.meta.json` records where they came from and when.
+
+```js
+import { itemPlan, itemWays, listWays } from '@r0cksolid/emerald-core';
+import {
+  committedDataDirectory,
+  loadItemCatalog,
+} from '@r0cksolid/emerald-core/loader';
+
+// `null`: load without the generated icon images, which this package does not include.
+const catalog = await loadItemCatalog(committedDataDirectory(), null);
+
+const { rows } = catalog.search('refined diamond', 5, 0);
+// rows[0].item: { id: 'REFINED_DIAMOND', displayName: 'Refined Diamond', rarity: 'EPIC', … }
+
+for (const way of listWays(itemWays(catalog, 'REFINED_DIAMOND')))
+  console.log(way.branch, way.method); // make forging
+
+const plan = itemPlan(catalog, 'REFINED_DIAMOND', 2);
+console.log(plan.steps.map((step) => `${step.count} × ${step.item}`));
+// [ '640 × ENCHANTED_DIAMOND', '4 × ENCHANTED_DIAMOND_BLOCK', '2 × REFINED_DIAMOND' ]
+console.log(
+  plan.materials.map((material) => `${material.count} × ${material.item}`),
+);
+// [ '102400 × DIAMOND' ]
+console.log(plan.totals); // { coins: 0, currencies: [], durationSeconds: 57600 }
+```
+
+`loadItemCatalog(directory, generatedDirectory, options?)` checks both files against their schemas and fails, naming the file, when one is missing, cannot be parsed, or has another schema version. Its second argument is never optional. With `null`, no image is read and the catalog's glyph table is empty. With a directory of the generated icon and glyph PNGs, every PNG the snapshot names must be in it, and each glyph's size is read from its file. The options' `levels` writes the levels of runes, enchanted books and minions as `roman`, the default, or `number`.
+
+Load the catalog once and keep it: it indexes the records when it is built and never changes afterwards. A newer snapshot means a new catalog.
+
+Outside Node, read `snapshot.json` and `snapshot.meta.json` yourself and pass their contents to `createItemCatalog(snapshot, meta, options?)` from the main entry. It trusts its input, so check the records against `SnapshotSchema` and `MetaSchema` first, for example with TypeBox's `Value.Check`.
+
+`itemPlan` throws an error naming an unknown id, and a `RangeError` for a count that is not a whole number of at least 1. Recipes carry a `completeness`, and a plan expands only complete ones.
+
+## Requirements
+
+Node 26 or later (`"engines": { "node": ">=26" }`).
+
+## Data sources and credits
+
+The snapshot is derived from these sources. `snapshot.meta.json` pins each one: the commits of NEU and SkyShards, the version or URL and the SHA-1 of the others, and `data/` keeps each source's original notice beside the snapshot.
+
+- **NotEnoughUpdates-REPO (NEU)**, MIT licence, copyright Moulberry; notice in `data/LICENSE`. NEU gives the item records, their names and lore, recipes, NPC offers and trades, mob drops, and pets' values at each level.
+- **SkyShards**, MIT licence, copyright Campion; notice in `data/LICENSE.skyshards`. SkyShards gives the attribute shards' fusion facts and their Attribute Menu text.
+- **Hypixel's SkyBlock resource pack**, under its own licence; notice in `data/LICENSE.hypixel`. Item icons and the pack's stat, skill and mob symbols are drawn from it. The snapshot records only the pack's URL and SHA-1, content hashes that name the generated images, and the private-use code points of its symbols.
+- **Hypixel's collections resource**, `https://api.hypixel.net/v2/resources/skyblock/collections`, from Hypixel's public API. It gives the collection items and the skill each is gathered in, which is how a plan knows an item is gathered by hand. It comes with no licence notice, so it is credited here.
+- **Minecraft**, by Mojang Studios, under the Minecraft EULA and the Microsoft Services Agreement; notice in `data/LICENSE.minecraft`. Icons are drawn from a pinned client jar's models and textures, and some game-font symbols from its font sheets. The snapshot records only the release, the jar's URL and SHA-1, and image content hashes. Player heads are named by the skin hash Minecraft's texture server uses.
+- **GNU Unifont**, the game font's fallback as Minecraft ships it, under the SIL Open Font License 1.1 or the GNU GPL version 2 or later with the font embedding exception; notice in `data/LICENSE.unifont`. Symbols that neither the pack nor Minecraft's sheets draw come from it. The snapshot records only its asset index pin and hashes.
+
+The package contains no pixels from the pack, Minecraft or Unifont, only the references and hashes above.
+
+## Licence
+
+The code is MIT, copyright R0ck Solid Software (`LICENSE`). The licence does not cover the snapshot's contents, which stay under their sources' terms above. Item names and lore are Hypixel's text, as NEU transcribes it.
+
+This package is not affiliated with or endorsed by Hypixel or Mojang. It is not an official Minecraft product.

package/data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Moulberry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/LICENSE.hypixel

@@ -0,0 +1,35 @@
+HYPIXEL SKYBLOCK RESOURCE PACK LICENSE
+
+======================================
+
+Version 1.0
+Effective Date: July 7, 2026
+Copyright © 2026 Hypixel Inc. All rights reserved.
+We made the Hypixel SkyBlock Resource Pack to make SkyBlock feel even more special, and we are happy to share it with you for free. It is licensed to you, not sold. By downloading or using the Pack, you agree to this License.
+
+WHAT YOU CAN DO
+---------------
+
+- Use the Pack to play on the Hypixel Network, on other people's servers, or in your own singleplayer worlds.
+- Tweak the Pack for your own personal use.
+- Create and share content that shows the Pack: videos, livestreams, shorts, screenshots, thumbnails, guides, wiki pages, reviews, fan art, and similar content. We love seeing what you make.
+- Earn money from that content through ads, subscriptions, donations, sponsorships, memberships, affiliate links, and similar creator revenue. Monetized YouTube and Twitch content is absolutely fine. As long as your content follows this License, you will never be in trouble with us for it.
+
+WHAT WE ASK YOU NOT TO DO
+-------------------------
+
+- Do not sell the Pack or its assets, or charge for access to them.
+- Do not use the Pack or its assets in or for your own business, product, or service. That includes servers you run, games, launchers, modpacks, marketplaces, merchandise, NFTs, and AI training. Websites and apps that are Hypixel related may use the Pack or its assets as long as it is not sold, or charged access for. This applies even if you never copy the files yourself, for example if you design your server or product so the Pack's art shows up in it.
+- Do not claim the Pack is yours, and do not suggest that Hypixel endorses you or your project.
+The creator content described above is the only exception, and it covers sharing and monetizing content, not selling things. Putting the Pack's art on merchandise or other products is off limits, even if you call it fan art.
+
+THE FINE PRINT
+--------------
+
+Hypixel Inc. owns the Pack and its assets. This License gives you permission, not ownership, and it covers only what Hypixel owns. Any game or platform you use the Pack with has its own rules, and those rules also apply to you.
+This License applies to every version of the Pack, old or new, so the creator permissions above cover content made with any version.
+If you use the Pack in ways this License does not allow, your permission ends. Content you shared while following the rules can stay up and stay monetized.
+The Pack is provided as is, with no warranties. We may update the Pack or this License for future releases at any time. Updates never take away permission for content you shared while following the rules at the time.
+Want to do something not covered here? Just ask us through Hypixel Support.
+Thanks for being part of SkyBlock, and have fun out there.
+https://hypixel.net/

package/data/LICENSE.minecraft

@@ -0,0 +1,4 @@
+Use of the contents of this archive is subject to the Minecraft End-User License Agreement (EULA) and the Microsoft Services Agreement.
+
+Minecraft EULA: https://aka.ms/MinecraftEULA
+Microsoft Services Agreement: https://www.microsoft.com/msa

package/data/LICENSE.skyshards

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Campion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.