@knowdev/splinterlib
v0.7.0
Published
Helper library for Splinterlands APIs
Downloads
15
Readme
Splinterlib 🔮
Helper library for Splinterlands APIs
ℹ️ What is Splinterlands?
Splinterlands is a digital NFT collectable card game that runs on the Hive blockchain. Its a lot like Magic the Gathering. What makes an NFT/blockchain game different is "true player ownership" of assets. In other words you can buy, sell, trade, or rent any of your assets with other players.
📋 Usage
Install
npm install --save @knowdev/splinterlib
Require
const Splinterlib = require("@knowdev/splinterlib");
See "Reference" (below) for a detailed API
Enable Logging
Requires a separate package which is already installed as a dependency
npm install --save @knowdev/log
const log = require("@knowdev/log");
Splinterlib.setLogger(log);
📖 Reference
- Wrapped Functions 🪄
- Async Battle History Iterator (
battleHistoryAsyncIterator
)
- Async Battle History Iterator (
- Helper Functions 💁
- Battle Filter (
battleFilter
) - Card Collection Filter (
cardCollectionFilter
)
- Battle Filter (
- Collections 🗂
- Models 🧱
- Direct API 🌐
- Battle History (
battleHistoryApi
) - Card Details (
cardDetailsApi
)
- Battle History (
- Constants 💬
Wrapped Functions 🪄
More convenient set of functions that interact with the underlying API
Async Battle History Iterator
/** Returns asyncIterator (see below) */
const battleHistory = await Splinterlib.battleHistoryAsyncIterator(
player, // Required string
{
beforeBlock, // Optional integer, starting Hive block to retrieve backwards from (defaults to current block)
filter, // Optional function returning true or false as to whether to include this battle in results (see "Battle Filter" below)
limit, // Optional integer, number of results per API call
max, // Optional integer, maximum results to return
resultsClass, // Optional class, used to instantiate each result
}
)
for await (const battle of battleHistory) {
//
}
Helper Functions 💁
Battle Filter
/** Returns function */
const filter = Splinterlib.battleFilter({
format, // Optional string, from BATTLE.FORMAT constant (below)
ignoreSurrender, // Optional boolean, default true
league, // Optional string, from LEAGUE constant (below)
loser, // Optional string, losing player
mana, // Optional integer, mana cap of match
manaPlusMinus, // Optional integer, range around mana to include, default 0
ruleset, // Optional array, from RULESET constant (below)
rulesetAnd, // Optional boolean, require all rulesets, default false
splinter, // Optional array, from SPLINTER constant (below)
winner, // Optional string, winning player
})
Card Collection Filter
/** Returns function */
const filter = Splinterlib.cardCollectionFilter({
ability, // Optional string or array of strings from ALL.ABILITIES (below)
abilityAnd, // Optional boolean, whether to require all passed abilities (default false)
edition, // Optional string or array of strings ("or" search), from ALL.CARD.EDITIONS (below)
format, // Optional string or array of strings ("and" search), from ALL.BATTLE.FORMATS constant (below)
mana, // Optional integer, mana of card; see below for more options
name, // Optional string, match beginning of words in card name
nameMatchAny, // Optional boolean, match anywhere in name (default false)
rarity, // Optional string or array of strings ("or" search), from ALL.CARD.RARITIES (below)
splinter, // Optional array or array of strings ("or" search), from ALL.SPLINTERS (below)
type, // Optional string, from ALL.CARD.TYPES (below)
});
const manaFilter = Splinterlib.cardCollectionFilter({
mana: {
[FILTER.GREATER_THAN_OR_EQUAL]: 3,
[FILTER.LESS_THAN_OR_EQUAL]: 6,
}
}).
Collections 🗂
Card Universe
Uses a cached version of card details unless process.env.SPLINTERLIB_FETCH
or process.env.SPLINTERLIB_FETCH_CARDS
is true
.
const cardArray = Splinterlib.cardUniverse.all();
const card = Splinterlib.cardUniverse.getTemplate(12);
// Pull fresh copy of card database from server
const cardArray = await Splinterlib.cardUniverse.refresh();
// Pull fresh copy of card database from QA server
const cardArray = await Splinterlib.cardUniverse.refresh({ qa: true });
Player Cards
TBD: card instances?
Site Settings
TBD
Models 🧱
Battle (model)
An instance of a particular battle that was waged or fled.
battle.createdDate;
battle.id;
battle.manaCap;
battle.winner;
battle.loser;
battle.rulesets;
battle.type;
battle.players;
battle.teams;
battle.formats;
Card Instance
Full characteristics about this particular instance of the card. In addition to template attributes this would include level, foil, alpha/beta edition.
Card Template
Partial characteristics about the card regardless of it's particular instance. E.g., type, splinter.
const card = Splinterlib.cardUniverse.getTemplate(12);
card.id = 12;
card.name = "Pirate Captain";
card.splinter = SPLINTER.WATER;
card.type = CARD.TYPE.MONSTER;
card.rarity = CARD.RARITY.COMMON;
card.isStarter = true;
card.edition = CARD.EDITION.ALPHA_BETA;
card.formats = [
BATTLE.FORMAT.ALPHA,
BATTLE.FORMAT.ALPHA_BETA,
BATTLE.FORMAT.NO_LEGENDARIES,
BATTLE.FORMAT.NO_LEGENDARY_SUMMONERS,
BATTLE.FORMAT.WILD,
];
Direct API 🌐
Direct implementations of the Splinterlands API with minimal parsing of encoded types
Battle History
/** Returns array of result objects */
const results = await Splinterlib.battleHistoryApi(
player, // Required string
{
beforeBlock, // Optional integer, starting Hive block to retrieve backwards from (defaults to current block)
limit, // Optional integer, number of results (default 50)
raw, // Optional boolean, skip parsing encoded objects and dates in results (default false)
types, // Advanced: optional string, defaults to "sm_battle,battle"
queryParams, // Advanced: optional object of additional parameters to pass to endpoint
}
);
Card Details
/** Returns array of card details */
const results = await Splinterlib.cardDetailsApi();
Constants 💬
const {
ALL,
BATTLE,
CARD,
LEAGUE,
RULESET,
SPLINTER,
} = require("@knowdev/splinterlib");
ALL
ALL.ABILITIES
ALL.BATTLE.FORMATS
ALL.CARD.EDITIONS
ALL.CARD.RARITIES
ALL.CARD.TYPES
ALL.SPLINTERS
BATTLE (constant)
BATTLE.FORMAT
BATTLE.FORMAT.ALPHA
BATTLE.FORMAT.ALPHA_BETA
BATTLE.FORMAT.GOLD
BATTLE.FORMAT.MODERN
BATTLE.FORMAT.NO_LEGENDARIES
BATTLE.FORMAT.NO_LEGENDARY_SUMMONERS
BATTLE.FORMAT.UNTAMED
BATTLE.FORMAT.UNTAMED_DICE
BATTLE.FORMAT.WILD
BATTLE.TYPE
BATTLE.TYPE.BRAWL
BATTLE.TYPE.RANKED
BATTLE.TYPE.SURRENDER
BATTLE.TYPE.TOURNAMENT
CARD
CARD.EDITION
CARD.EDITION.ALPHA
CARD.EDITION.ALPHA_BETA
(interpreted to mean cards from alpha or beta)CARD.EDITION.BETA
CARD.EDITION.PROMO
CARD.EDITION.REWARD
CARD.EDITION.UNTAMED
CARD.EDITION.DICE
CARD.EDITION.GLADIUS
CARD.RARITY
CARD.RARITY.COMMON
CARD.RARITY.RARE
CARD.RARITY.EPIC
CARD.RARITY.LEGENDARY
CARD.TYPE
CARD.TYPE.MONSTER
CARD.TYPE.SUMMONER
FILTER
FILTER.EQUALS
FILTER.LESS_THAN
FILTER.LESS_THAN_OR_EQUAL
FILTER.GREATER_THAN
FILTER.GREATER_THAN_OR_EQUAL
LEAGUE
LEAGUE.NOVICE
LEAGUE.BRONZE
LEAGUE.SILVER
LEAGUE.GOLD
LEAGUE.DIAMOND
LEAGUE.CHAMPION
LEAGUE.SUMMONER_CAPS
Each key contains an object with COMMON
, RARE
, EPIC
, and LEGENDARY
LEAGUE.SUMMONER_CAPS.NOVICE
LEAGUE.SUMMONER_CAPS.BRONZE
LEAGUE.SUMMONER_CAPS.SILVER
LEAGUE.SUMMONER_CAPS.GOLD
LEAGUE.SUMMONER_CAPS.DIAMOND
LEAGUE.SUMMONER_CAPS.CHAMPION
RULESET
RULESET.AIM_TRUE
RULESET.ARMORED_UP
RULESET.BACK_TO_BASICS
RULESET.BROKEN_ARROWS
RULESET.CLOSE_RANGE
RULESET.EARTHQUAKE
RULESET.EQUAL_OPPORTUNITY
RULESET.EQUALIZER
RULESET.EVEN_STEVENS
RULESET.EXPLOSIVE_WEAPONRY
RULESET.FOG_OF_WAR
RULESET.HEALED_OUT
RULESET.HEAVY_HITTERS
RULESET.HOLY_PROTECTION
RULESET.KEEP_YOUR_DISTANCE
RULESET.LITTLE_LEAGUE
RULESET.LOST_LEGENDARIES
RULESET.LOST_MAGIC
RULESET.MELEE_MAYHEM
RULESET.NOXIOUS_FUMES
RULESET.ODD_ONES_OUT
RULESET.REVERSE_SPEED
RULESET.RISE_OF_THE_COMMONS
RULESET.SILENCED_SUMMONERS
RULESET.SPREADING_FURY
RULESET.STAMPEDE
RULESET.STANDARD
RULESET.SUPER_SNEAK
RULESET.TAKING_SIDES
RULESET.TARGET_PRACTICE
RULESET.UNPROTECTED
RULESET.UP_CLOSE_AND_PERSONAL
RULESET.WEAK_MAGIC
SPLINTER
SPLINTER.DEATH
SPLINTER.DRAGON
SPLINTER.EARTH
SPLINTER.FIRE
SPLINTER.LIFE
SPLINTER.WATER
🚀 Deployment
npm publish --access=public
📝 Changelog
- 0.6.6: Fix bug on modern reward definition
- 0.6.5: Filter on multiple formats
- 0.6.4: Export cardCollectionFilter
- 0.6.3: Card universe returns abilities(), initial Chaos Legion support
- 0.6.2: Expand
ALL
constant, allow refresh against QA server - 0.6.0: Card collection filtering
- 0.5.0: Breaking change: rename cardUniverse get to getTemplate 💥
- 0.4.0: Breaking change: rename parameters 💥
- 0.3.0: Battle filter
- 0.2.1: Constants
- 0.2.0: Battle history iterator
- 0.1.0: Battle history API
🛣 Roadmap
- ~~Card Universe: Filtering~~
- ~~Interactive Demo of Card Universe~~ (done but never done)
- Player Collection: Filtering
- At least by edition
- Get Guild
- 🛡 Guild Report
- Interactive Demo of Player Collections
Task List ☑️
- Card Template
- Card images
- Crop
- ...Filter abilities/stats by league caps
- Card images
- Card Universe
- ...Card Sort
- Stats
- Card filter
- Limit to league cap
- ...Card Sort
- Player collection
- Card instances
- Abilities
- Stats
- Card filter
- Card instances
- Battle Summary
- Mana
- Rulesets
- Available splinters
- Monster
- Damage
- Blocked
- Kills
- Taken
- Move (position)
- Count
- Killed (round)
- Position
- Damage
- Interactive Demo
- Card universe
- Player collection
- Battle history
Wishlist 🌠
All of the APIs! ⚡️🧙♂️⚡️
- 🔮 Active quest
- 🛡 Follow
- 🛡 Report
📜 License
All rights reserved. Safe for use around pets.