@dchighs/dc-core 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,211 @@
+# dc-core
+
+`@dchighs/dc-core` is a TypeScript/JavaScript library that simulates core Dragon City game logic.
+
+It provides:
+
+- **Calculators** for attack damage, feed cost, orb recall gain, and element strengths/weaknesses.
+- **Validation tools** for dragon metadata.
+- **Static configuration** for dragons, islands, sounds, elements, and more.
+- **Enums** for strongly-typed values used across the package.
+
+## Installation
+
+```bash
+npm install @dchighs/dc-core
+```
+
+## Quick start
+
+```ts
+import {
+  calculateAttackDamage,
+  calculateDragonFeedCost,
+  calculateElementStrengths,
+  DragonElement,
+} from "@dchighs/dc-core"
+
+const damage = calculateAttackDamage({
+  attackPower: 1800,
+  dragon: {
+    category: 9,
+    level: 40,
+    rank: 2,
+    stars: 3,
+  },
+})
+
+console.log(damage)
+// { minimum: ..., maximum: ..., average: ..., random: ... }
+
+const feedCost = calculateDragonFeedCost({ initialLevel: 1, finalLevel: 40 })
+console.log(feedCost)
+
+const strengths = calculateElementStrengths(DragonElement.Legend)
+console.log(strengths)
+```
+
+## Main exports
+
+### Calculators
+
+- `calculateAttackDamage(options)`
+- `calculateDragonFeedCost(options)`
+- `calculateElementStrengths(element)`
+- `calculateElementsStrengths(elements)`
+- `calculateElementWeaknesses(element)`
+- `calculateOrbRecallGain(options)`
+
+#### `calculateAttackDamage(options)`
+
+Calculates the expected damage range for a dragon attack.
+
+- **Input**
+  - `attackPower: number`
+  - `dragon: { category: number; level: number; rank: number; stars: number }`
+- **Validation**
+  - Checks category, rank, and level/stars compatibility.
+- **Output**
+  - `{ minimum: number; maximum: number; average: number; random: number }`
+- **Notes**
+  - Uses dragon category, level scaling, rank bonus, and star bonus from `dragonSettings`.
+  - `random` is sampled from the internal damage variance range.
+
+#### `calculateDragonFeedCost(options)`
+
+Computes the total food required based on dragon levels.
+
+- **Input**
+  - `initialLevel: number`
+  - `finalLevel: number`
+- **Validation**
+  - Validates both levels and throws if `initialLevel > finalLevel`.
+- **Output**
+  - `number` (total food cost)
+
+#### `calculateElementStrengths(element)`
+
+Returns which elements are strong against a single element.
+
+- **Input**
+  - `element: string` (ideally from `DragonElement`)
+- **Validation**
+  - Validates if the element exists in internal settings.
+- **Output**
+  - `DragonElement[]`
+
+#### `calculateElementsStrengths(elements)`
+
+Combines strengths for multiple elements and removes duplicates.
+
+- **Input**
+  - `elements: string[]`
+- **Validation**
+  - Validates each provided element.
+- **Output**
+  - `string[]` with unique strengths from all provided elements.
+
+#### `calculateElementWeaknesses(element)`
+
+Returns which elements can hit the provided element effectively.
+
+- **Input**
+  - `element: string` (ideally from `DragonElement`)
+- **Validation**
+  - Validates if the element exists in internal settings.
+- **Output**
+  - `DragonElement[]`
+
+#### `calculateOrbRecallGain(options)`
+
+Calculates how many orbs are returned when recalling a dragon.
+
+- **Input**
+  - `level: number`
+  - `stars?: number` (defaults to `0`)
+- **Validation**
+  - Validates level/stars compatibility.
+- **Output**
+  - `number` (total recalled orbs)
+- **Notes**
+  - Recall level contribution is capped internally at level `30`.
+
+### Tools
+
+- `validateDragonLevelCompatibilityWithStars(options)`
+- `validateDragonCategory(category, options?)`
+- `validateDragonRarity(rarity, options?)`
+- `validateDragonStars(stars, options?)`
+- `validateElementName(element, options?)`
+- `validateDragonLevel(level, options?)`
+- `validateDragonRank(rank, options?)`
+- `getMusicKeyNameFromTag(tag)`
+- `DragonStaticFileUrlParser`
+
+### Settings
+
+- `dragonSettings`
+- `feedCostSettings`
+- `orbRecallReturnSettings`
+- `elementSettings`
+- `islandSettings`
+- `soundSettings`
+
+### Enums
+
+All enums are exported from the package root, including:
+
+- `DragonElement`
+- `DragonRarity`
+- `DragonCategory`
+- `DragonRank`
+- `DragonPhase`
+- `ConfigPlatform`
+- `ConfigLanguage`
+
+## Example: validating values before calculations
+
+```ts
+import {
+  validateDragonLevelCompatibilityWithStars,
+  validateDragonCategory,
+  validateDragonRank,
+} from "@dchighs/dc-core"
+
+validateDragonLevelCompatibilityWithStars({
+  level: 40,
+  stars: 3,
+  throwOnError: true,
+})
+
+validateDragonCategory(9, { throwOnError: true })
+validateDragonRank(2, { throwOnError: true })
+```
+
+## Example: parsing static asset URLs
+
+```ts
+import { DragonStaticFileUrlParser } from "@dchighs/dc-core"
+
+const spriteUrl = "https://aws-static.socialpointgames.com/static/dragoncity/mobile/ui/dragons/112_terra_3@2x.png"
+
+const parsed = DragonStaticFileUrlParser.parseFromSprite(spriteUrl)
+console.log(parsed)
+// {
+//   platformPrefix: 'aws',
+//   id: 112,
+//   imageName: '112_terra',
+//   phase: 3,
+//   skin: null,
+//   imageQuality: '@2x'
+// }
+```
+
+## Notes
+
+- Functions may throw if invalid values are provided and `throwOnError: true` is used.
+- This package is distributed as CommonJS with TypeScript definitions.
+
+## License
+
+MIT

package/dist/calculators/calculate-breeding-results.d.ts

@@ -0,0 +1,60 @@
+export type CalculateBreedingResultsParentConfig = {
+    id: number;
+    elements: string[];
+    level: number;
+    empowerLevel?: number;
+};
+export type CalculateBreedingResultsConfigOptions = {
+    breeding: Array<{
+        element_one: string;
+        element_two: string;
+        dragon_id_1: number;
+        empower_1: number;
+        dragon_id_2: number;
+        empower_2: number;
+        dragon_id_3: number;
+        empower_3: number;
+        dragon_id_4?: number;
+        empower_4?: number;
+        dragon_id_5?: number;
+        empower_5?: number;
+        dragon_id_6?: number;
+        empower_6?: number;
+        dragon_id_7?: number;
+        empower_7?: number;
+    }>;
+    incompatibilities?: Array<{
+        element_one: string;
+        element_two: string;
+    }>;
+    soulmates?: Array<{
+        parent_1_id: number;
+        parent_2_id: number;
+        dragon_id: number;
+        chance: number;
+        level_parents: number;
+    }>;
+    specialBreeding?: Array<{
+        condition1: {
+            id: number[];
+        };
+        condition2: {
+            id: number[];
+        };
+        result: number;
+    }>;
+    sanctuaryUnlockedDragons?: number[];
+};
+export type CalculateBreedingResultsOptions = {
+    parent1: CalculateBreedingResultsParentConfig;
+    parent2: CalculateBreedingResultsParentConfig;
+    config: CalculateBreedingResultsConfigOptions;
+};
+export type BreedingSource = "soulmate" | "special" | "sanctuary" | "regular";
+export type BreedingResultItem = {
+    dragonId: number;
+    sources: BreedingSource[];
+    requiredEmpower?: number;
+    chance?: number;
+};
+export declare function calculateBreedingResults({ parent1, parent2, config }: CalculateBreedingResultsOptions): BreedingResultItem[];

package/dist/calculators/calculate-breeding-results.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateBreedingResults = calculateBreedingResults;
+function calculateBreedingResults({ parent1, parent2, config }) {
+    var _a;
+    const resultsMap = new Map();
+    function addResult(dragonId, source, empower, chance) {
+        if (!dragonId)
+            return;
+        const existing = resultsMap.get(dragonId);
+        if (existing) {
+            if (!existing.sources.includes(source)) {
+                existing.sources.push(source);
+            }
+            if (empower !== undefined) {
+                existing.requiredEmpower = existing.requiredEmpower !== undefined ? Math.min(existing.requiredEmpower, empower) : empower;
+            }
+            if (chance !== undefined) {
+                existing.chance = Math.max(existing.chance || 0, chance);
+            }
+        }
+        else {
+            resultsMap.set(dragonId, {
+                dragonId,
+                sources: [source],
+                requiredEmpower: empower,
+                chance
+            });
+        }
+    }
+    if (config.specialBreeding) {
+        for (const special of config.specialBreeding) {
+            const matchesP1Cond1 = special.condition1.id.includes(parent1.id);
+            const matchesP2Cond2 = special.condition2.id.includes(parent2.id);
+            const matchesP1Cond2 = special.condition2.id.includes(parent1.id);
+            const matchesP2Cond1 = special.condition1.id.includes(parent2.id);
+            if ((matchesP1Cond1 && matchesP2Cond2) || (matchesP1Cond2 && matchesP2Cond1)) {
+                addResult(special.result, "special");
+            }
+        }
+    }
+    if (config.soulmates) {
+        for (const soulmate of config.soulmates) {
+            const matches = (soulmate.parent_1_id === parent1.id && soulmate.parent_2_id === parent2.id) ||
+                (soulmate.parent_1_id === parent2.id && soulmate.parent_2_id === parent1.id);
+            const levelsMatch = parent1.level >= soulmate.level_parents && parent2.level >= soulmate.level_parents;
+            if (matches && levelsMatch) {
+                addResult(soulmate.dragon_id, "soulmate", undefined, soulmate.chance);
+            }
+        }
+    }
+    const incompatibilities = config.incompatibilities || [];
+    const isIncompatible = (e1, e2) => {
+        return incompatibilities.some(inc => (inc.element_one === e1 && inc.element_two === e2) ||
+            (inc.element_one === e2 && inc.element_two === e1));
+    };
+    for (const e1 of parent1.elements) {
+        for (const e2 of parent2.elements) {
+            if (isIncompatible(e1, e2)) {
+                continue;
+            }
+            const breedingRule = config.breeding.find(b => (b.element_one === e1 && b.element_two === e2) ||
+                (b.element_one === e2 && b.element_two === e1));
+            if (breedingRule) {
+                const pairs = [
+                    { id: breedingRule.dragon_id_1, emp: breedingRule.empower_1 },
+                    { id: breedingRule.dragon_id_2, emp: breedingRule.empower_2 },
+                    { id: breedingRule.dragon_id_3, emp: breedingRule.empower_3 },
+                    { id: breedingRule.dragon_id_4, emp: breedingRule.empower_4 },
+                    { id: breedingRule.dragon_id_5, emp: breedingRule.empower_5 },
+                    { id: breedingRule.dragon_id_6, emp: breedingRule.empower_6 },
+                    { id: breedingRule.dragon_id_7, emp: breedingRule.empower_7 },
+                ];
+                for (const pair of pairs) {
+                    if (pair.id) {
+                        const isSanctuary = (_a = config.sanctuaryUnlockedDragons) === null || _a === void 0 ? void 0 : _a.includes(pair.id);
+                        addResult(pair.id, isSanctuary ? "sanctuary" : "regular", pair.emp || 0);
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(resultsMap.values());
+}

package/dist/calculators/calculate-element-weaknesses.js

@@ -6,9 +6,9 @@ const elements_1 = require("../settings/elements");
 function calculateElementWeaknesses(element) {
     (0, validate_element_name_1.validateElementName)(element, { throwOnError: true });
     const weaknesses = [];
-    for (const element in elements_1.elementSettings) {
-        if (elements_1.elementSettings[element].strengths.includes(element)) {
-            weaknesses.push(element);
+    for (const key in elements_1.elementSettings) {
+        if (elements_1.elementSettings[key].strengths.includes(element)) {
+            weaknesses.push(key);
         }
     }
     return weaknesses;

package/dist/calculators/index.d.ts

@@ -4,4 +4,7 @@ import { calculateElementStrengths } from "./calculate-element-strengths";
 import { calculateDragonFeedCost } from "./calculate-dragon-feed-cost";
 import { calculateOrbRecallGain } from "./calculate-orb-recall-gain";
 import { calculateAttackDamage } from "./calculate-attack-damage";
-export { calculateOrbRecallGain, calculateAttackDamage, calculateDragonFeedCost, calculateElementsStrengths, calculateElementWeaknesses, calculateElementStrengths };
+import { calculateBreedingResults } from "./calculate-breeding-results";
+export * from "./calculate-breeding-results";
+import { calculateElementResistances } from "./calculate-element-resistances";
+export { calculateElementResistances, calculateOrbRecallGain, calculateAttackDamage, calculateDragonFeedCost, calculateElementsStrengths, calculateElementWeaknesses, calculateElementStrengths, calculateBreedingResults };

package/dist/calculators/index.js

@@ -1,6 +1,20 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateElementStrengths = exports.calculateElementWeaknesses = exports.calculateElementsStrengths = exports.calculateDragonFeedCost = exports.calculateAttackDamage = exports.calculateOrbRecallGain = void 0;
+exports.calculateBreedingResults = exports.calculateElementStrengths = exports.calculateElementWeaknesses = exports.calculateElementsStrengths = exports.calculateDragonFeedCost = exports.calculateAttackDamage = exports.calculateOrbRecallGain = exports.calculateElementResistances = void 0;
 const calculate_elements_strengths_1 = require("./calculate-elements-strengths");
 Object.defineProperty(exports, "calculateElementsStrengths", { enumerable: true, get: function () { return calculate_elements_strengths_1.calculateElementsStrengths; } });
 const calculate_element_weaknesses_1 = require("./calculate-element-weaknesses");
@@ -13,3 +27,8 @@ const calculate_orb_recall_gain_1 = require("./calculate-orb-recall-gain");
 Object.defineProperty(exports, "calculateOrbRecallGain", { enumerable: true, get: function () { return calculate_orb_recall_gain_1.calculateOrbRecallGain; } });
 const calculate_attack_damage_1 = require("./calculate-attack-damage");
 Object.defineProperty(exports, "calculateAttackDamage", { enumerable: true, get: function () { return calculate_attack_damage_1.calculateAttackDamage; } });
+const calculate_breeding_results_1 = require("./calculate-breeding-results");
+Object.defineProperty(exports, "calculateBreedingResults", { enumerable: true, get: function () { return calculate_breeding_results_1.calculateBreedingResults; } });
+__exportStar(require("./calculate-breeding-results"), exports);
+const calculate_element_resistances_1 = require("./calculate-element-resistances");
+Object.defineProperty(exports, "calculateElementResistances", { enumerable: true, get: function () { return calculate_element_resistances_1.calculateElementResistances; } });

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@dchighs/dc-core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A library focused on simulating some of the logic of the game Dragon City.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/*",
-    "!/**/__tests__"
+    "!/**/__tests__",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "jest",
+    "test:coverage": "jest --coverage",
     "build": "tsc"
   },
   "keywords": [
@@ -31,6 +34,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dchighs/dc-core.git"
+    "url": "https://github.com/dc-highs/dc-core.git"
   }
 }