Project Gorgon Data

Typed game data library for Project Gorgon — an indie MMORPG by Elder Game, LLC.

Provides Zod-validated schemas for all client data files, pre-loaded typed Map collections, crafting/gardening/nature appreciation skill planners, a build calculator with damage computation, a combat simulator, a match-3 puzzle engine, and helper utilities for items, recipes, and keywords.

Installation

npm install project-gorgon-data
# or
pnpm add project-gorgon-data

zod is a peer dependency:

npm install zod

Quick Start

import { recipes, items, skills, RAW_XP_TABLES } from 'project-gorgon-data';
import { planCraftingSkill, buildXpTableLookup, CharacterState } from 'project-gorgon-data';

// Load a character export
const state = new CharacterState();
state.loadReport(characterJson);

// Plan leveling Cooking to 30
const xpTables = buildXpTableLookup(RAW_XP_TABLES);
const plan = planCraftingSkill(state, 'Cooking', { targetLevel: 30 }, recipes, skills, xpTables);
console.log(`${plan.totalCrafts} crafts, ${plan.totalXpGained} XP`);

Sub-path Imports

Import only what you need for smaller bundles:

import { recipes, items } from 'project-gorgon-data/data';
import { RecipeSchema, ItemSchema } from 'project-gorgon-data/schemas';
import { planCraftingSkill } from 'project-gorgon-data/planner';
import { getItemName, buildKeywordIndex } from 'project-gorgon-data/helpers';
import { generateBoard, applyMove } from 'project-gorgon-data/match3';

Import Path	Contents
`project-gorgon-data`	Everything re-exported
`project-gorgon-data/schemas`	Zod schemas + inferred TypeScript types
`project-gorgon-data/data`	Pre-loaded `Map` instances + raw JSON
`project-gorgon-data/data/items`	Items only
`project-gorgon-data/data/recipes`	Recipes only
`project-gorgon-data/data/skills`	Skills only
`project-gorgon-data/data/abilities`	Abilities only
`project-gorgon-data/data/npcs`	NPCs only
`project-gorgon-data/data/areas`	Areas only
`project-gorgon-data/data/sources`	Source lookups (abilities, items, recipes)
`project-gorgon-data/planner`	Crafting, gardening, and nature appreciation planners
`project-gorgon-data/helpers`	Item, recipe, keyword, build, and combat helpers
`project-gorgon-data/match3`	Match-3 puzzle engine

Data

All game data is pre-loaded into typed Map collections keyed by internal ID.

Export	Type	Description
`items`	`Map<string, Item>`	All game items keyed by `item_<id>`
`recipes`	`Map<string, Recipe>`	All game recipes keyed by `recipe_<id>`
`skills`	`Map<string, Skill>`	All game skills keyed by skill name
`abilities`	`Map<string, Ability>`	All abilities keyed by `ability_<id>`
`npcs`	`Map<string, Npc>`	All NPCs keyed by internal name
`areas`	`Map<string, Area>`	Game areas
`effects`	`Map<string, Effect>`	Buffs, debuffs, and ability modifiers
`tsysClientInfo`	`Map<string, TsysClientInfo>`	Treasure system powers and tiers
`advancementTables`	`Map<string, AdvancementTable>`	Skill advancement tables
`quests`	`Map<string, Quest>`	All quests
`RAW_XP_TABLES`	`Record<string, XpTable>`	Raw XP table data. Pass to `buildXpTableLookup()`

Additional data exports: abilityKeywords, abilityDynamicDots, attributes, directedGoals, landmarks, lorebookInfo, lorebooks, playerTitles, storageVaults, tsysProfiles, and corresponding RAW_* constants.

Schemas

All data types have Zod schemas with .strict() validation. Schemas are exported alongside their inferred TypeScript types:

import { RecipeSchema, type Recipe } from 'project-gorgon-data/schemas';

const parsed = RecipeSchema.parse(rawData);

Schemas are available for: abilities, areas, items, itemUses, recipes, NPCs, skills, effects, attributes, quests, storageVaults, tsysClientInfo, tsysProfiles, xpTables, advancementTables, AI, abilityKeywords, abilityDynamicDots, abilityDynamicSpecialValues, directedGoals, landmarks, lorebookInfo, lorebooks, playerTitles, sourcesAbilities, sourcesItems, sourcesRecipes, characterReport, and storageReport.

Character State

Load character sheet and storage exports from the game:

import { CharacterState } from 'project-gorgon-data';

const state = new CharacterState();
state.loadReport(characterSheetJson);  // Auto-detects report type
state.loadReport(storageJson);         // Load storage separately

state.characterName;          // string | null
state.skills;                 // Map<string, CharacterSkillEntry>
state.recipeCompletions;      // Map<string, number> — InternalName -> times crafted
state.currentStats;           // Map<string, number>
state.allItems;               // StorageItem[] — all items from storage report
state.inventoryItems;         // StorageItem[] — items in inventory
state.vaultItems;             // StorageItem[] — items in storage vaults
state.getItemsByVault(name);  // StorageItem[] — items in a specific vault
state.vaultNames;             // string[] — all vault names
state.equippedItems;          // StorageItem[] — equipped gear

Standalone parse functions are also available: parseReport(data), parseCharacterReport(data), parseStorageReport(data).

Crafting Planner

Greedy simulation that picks the best recipe at each step to level a crafting skill:

import { planCraftingSkill, buildXpTableLookup, groupStepsIntoRuns } from 'project-gorgon-data/planner';
import { recipes, skills, RAW_XP_TABLES } from 'project-gorgon-data/data';

const xpTables = buildXpTableLookup(RAW_XP_TABLES);
const plan = planCraftingSkill(state, 'Cooking', {
  targetLevel: 30,
  strategy: 'efficient',           // 'xp' (default) or 'efficient'
  includeRecipes: new Set(['Butter']),
  excludeRecipes: new Set(['MildCheddarCheese']),
  unlockPrereqs: true,
  inventory: new Map([[13101, 50]]),
}, recipes, skills, xpTables);

const runs = groupStepsIntoRuns(plan.steps);

Planner Options

{
  targetLevel: number;
  maxCrafts?: number;              // Safety cap (default 10000)
  strategy?: 'xp' | 'efficient';  // Scoring mode (default 'xp')
  itemEffort?: ItemEffortMap;      // Per-item effort overrides
  includeRecipes?: Set<string>;    // Extra recipes to treat as known
  excludeRecipes?: Set<string>;    // Recipes to skip
  unlockPrereqs?: boolean;         // Auto-unlock PrereqRecipe chains
  inventory?: Map<number, number>; // ItemCode -> quantity available
}

Plan Result

{
  skill: string;
  startLevel: number;
  endLevel: number;
  targetLevel: number;
  targetReached: boolean;
  steps: CraftStep[];
  totalCrafts: number;
  totalXpGained: number;
  totalEffort: number;
  levelUps: number;
  ingredientTotals: Map<number, IngredientUsage>;
  keywordIngredientTotals: Map<string, IngredientUsage>;
  inventoryRemaining?: Map<number, number>;
}

Strategies

xp (default): Pick the recipe with the highest effective XP per craft.
efficient: Pick the recipe with the highest XP per effort. Effort is the sum of stackSize * chanceToConsume * itemEffort across all ingredients. Tools with low ChanceToConsume (e.g. 3%) contribute very little effort.

XP Functions

Function	Description
`buildXpTableLookup(rawXpTables)`	Converts raw XP table data into a `Map<string, number[]>` lookup
`getXpRequiredForLevel(name, level, lookup)`	XP needed to advance from `level` to `level + 1`
`calcRecipeXp(recipe, level, count, mod?)`	Effective XP for a single craft including first-time bonus and drop-off
`calcRecipeEffort(recipe, itemEffort?)`	Effort cost per craft
`calcDropOffMultiplier(level, dropOff?, rate?, pct?)`	XP drop-off multiplier

Ingredient Helpers

Function	Description
`buildItemRecipeLookup(recipes)`	Reverse lookup: ItemCode -> recipes that produce it
`findRecipesForItem(code, lookup)`	Recipes producing a given item
`resolveIngredientTree(code, qty, recipes, lookup?, depth?)`	Recursive ingredient resolution
`annotateCraftableIngredients(tree, state, recipes)`	Mark which ingredients are craftable
`computeIngredientTotalsFromSteps(steps, recipes, items)`	Aggregate ingredient needs from plan steps

Step Grouping

import { groupStepsIntoRuns } from 'project-gorgon-data/planner';

const runs = groupStepsIntoRuns(plan.steps);
// CraftRun: { recipeName, internalName, count, firstCrafts, totalXp, levelStart, levelEnd }

Gardening Planner

Simulates concurrent multi-slot gardening with real-time constraints:

import { planGardeningSkill, groupActionsIntoPhases } from 'project-gorgon-data/planner';

const plan = planGardeningSkill(state, {
  targetLevel: 30,
  slotGroups: DEFAULT_SLOT_GROUPS,
  timing: DEFAULT_GARDENING_TIMING,
}, skills, xpTables);

const phases = groupActionsIntoPhases(plan.actions);

Models plant growth, watering, fertilizer crafting/consumption, strange dirt boosts, and water refill cycles. Returns detailed action logs, harvest runs, seed/fertilizer usage, and XP-per-hour metrics.

Nature Appreciation Planner

Plans sequential flower uses to level Nature Appreciation:

import { planNatureAppreciation, groupFlowerUsesIntoPhases } from 'project-gorgon-data/planner';

const plan = planNatureAppreciation(state, { targetLevel: 30 }, skills, xpTables);
const phases = groupFlowerUsesIntoPhases(plan.steps);

Optionally generates a companion gardening plan for growing the needed flowers.

Helpers

Item Helpers

import { getItemByCode, getItemName } from 'project-gorgon-data/helpers';

const item = getItemByCode(5001, items);  // Look up by numeric ItemCode
const name = getItemName(5001, items);    // "Onion" (falls back to "Item #5001")

Keyword Helpers

import { buildKeywordIndex, findItemsByKeyword, findItemsByKeywords } from 'project-gorgon-data/helpers';

const index = buildKeywordIndex(items);
const fruits = findItemsByKeyword('Fruit', index);
const matches = findItemsByKeywords(['Fruit', '!Poison'], index);  // Fruit AND NOT Poison

Recipe Helpers

import { resolveRecipe, resolveRecipeIngredients } from 'project-gorgon-data/helpers';

const resolved = resolveRecipe('recipe_1234', recipe, items, keywordIndex);
// ResolvedRecipe: { ingredients: ResolvedIngredient[], results: ResolvedResultItem[] }

Build Helpers

Gear mod filtering, effect parsing, and damage calculation for the build planner:

import {
  getAvailablePowers,
  getAvailableTiers,
  parseEffectDesc,
  collectAbilityAttributes,
  calculateAbilityDamage,
  getCombatAbilities,
  encodeBuildToHash,
  decodeBuildFromHash,
} from 'project-gorgon-data/helpers';

Function	Description
`getAvailablePowers(slot, skill, tsysClientInfo)`	Filter treasure powers by gear slot and skill
`getAvailableTiers(power, rarity)`	Get tiers available at a given rarity
`parseEffectDesc(desc)`	Parse `{ATTR}{VALUE}{CONTEXT}` format effect descriptions
`collectAbilityAttributes(ability, keywords, skills, dots, map?)`	Build attribute buckets for damage scaling
`calculateAbilityDamage(ability, attrs, effects, textEffects?)`	Full damage result with DoTs, crit, stats
`getCombatAbilities(skill, abilities, maxLevel?)`	Player-facing abilities filtered and grouped by upgrade root
`encodeBuildToHash(input)` / `decodeBuildFromHash(hash)`	Serialize builds to shareable URL hashes

Skill Effects

Per-skill effect configs for 30+ combat skills (Sword, Fire Magic, Psychology, Bard, etc.):

import { resolveSkillEffects, applyResolvedEffects } from 'project-gorgon-data/helpers';

const effects = resolveSkillEffects(powerId, effectDescs, slot);
applyResolvedEffects(damageResult, effects);

Combat Simulator

Simulate ability rotations and compute DPS:

import { simulateCombat } from 'project-gorgon-data/helpers';

const result = simulateCombat(config);
// CombatSimResult: per-ability DPS, timeline, enemy results, total damage

Match-3 Engine

Board-based match-3 puzzle game engine with cascading, scoring, and simulation:

import {
  generateBoard,
  createIdSource,
  applyMove,
  getAllValidMoves,
  simulateGameSummary,
  seededRng,
} from 'project-gorgon-data/match3';

const board = generateBoard(8, 6, createIdSource(), seededRng(42));
const moves = getAllValidMoves(board, 8);
const result = applyMove(board, moves[0].from, moves[0].to, 6, 8, createIdSource());

Function	Description
`generateBoard(size, k, idSource, rng?)`	Create a `size x size` board with `k` gem types, no initial matches
`findMatches(board, size)`	Find all 3+ tile match groups
`applyMove(board, from, to, k, size, idSource, rng?)`	Execute a swap with full cascade resolution
`getAllValidMoves(board, size)`	List all legal moves
`simulateGameSummary(seed, config, solver, turns)`	Play N turns and return summary stats
`simulateGameReplay(seed, config, moves)`	Replay an exact move sequence
`reshuffleIfDead(board, size, k, idSource, rng?)`	Reshuffle if no valid moves exist

Validation

Validate raw JSON data against Zod schemas:

import { validate, validateFile } from 'project-gorgon-data';

const result = validate();         // Validate all data files
const single = validateFile('items');  // Validate a single data file

Supported files: abilities, items, recipes, skills, NPCs, areas, effects, quests, and 20+ more.

Key Types

CraftStep

{
  recipeId: string;
  recipeName: string;
  internalName: string;
  xpGained: number;
  effortCost: number;
  isFirstCraft: boolean;
  skillLevelBefore: number;
  skillLevelAfter: number;
}

IngredientUsage

{
  totalCount: number;
  timesUsed: number;
  chanceToConsume: number;
  recipeCount: number;
  usedByRecipes: Set<string>;
}

RecipeSource

{
  recipeId: string;
  recipe: Recipe;
  outputStackSize: number;
  percentChance?: number;
}

IngredientNode

{
  itemCode: number | null;
  keywords?: string[];
  quantity: number;
  craftableVia: RecipeSource[];
  subIngredients?: IngredientNode[];
}

Development

Setup

git clone https://github.com/hjarrell/project-gorgon-data.git
cd project_gorgon_data
pnpm install

Commands

Command	Description
`pnpm build`	Compile TypeScript (CJS + ESM)
`pnpm test`	Run tests (vitest)
`pnpm run clean`	Remove dist directories
`pnpm run analyze <file>`	Analyze a JSON data file's structure
`pnpm run update-files`	Fetch latest game data from CDN
`pnpm run diff-data`	Diff local data against previous version
`pnpm run update-icons`	Download game icons from CDN

CLI Crafting Planner

A CLI wrapper around the crafting planner for local development:

npx tsx scripts/plan-crafting.ts <character-json> <skill> <target-level> [flags]

Flags

Flag	Description
`--efficient`	Score recipes by XP per effort instead of raw XP
`--effort-file <path>`	JSON file mapping ItemCode to effort value (used with `--efficient`)
`--include-recipes <path>`	JSON array of recipe InternalNames to treat as known
`--exclude-recipes <path>`	JSON array of recipe InternalNames to skip
`--inventory <path>`	JSON file mapping ItemCode to quantity available
`--unlock-prereqs`	Auto-unlock recipes via PrereqRecipe chains
`--verbose`	Show every individual craft step

Examples

# Level Cooking to 30
npx tsx scripts/plan-crafting.ts src/example/Character_ShepardPiedPiper.json Cooking 30

# Efficient mode with inventory constraints
npx tsx scripts/plan-crafting.ts src/example/Character_ShepardPiedPiper.json Cooking 30 --efficient --inventory inventory.json

# Include extra recipes and auto-unlock prereq chains
npx tsx scripts/plan-crafting.ts src/example/Character_ShepardPiedPiper.json Fletching 30 --include-recipes fletching-recipes.json --unlock-prereqs

Adding a New Schema

See instructions.md for the step-by-step workflow for adding Zod schemas to new data files.

Game Data

Raw JSON data files are sourced from the Project Gorgon CDN. Use pnpm run update-files to fetch the latest version.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
scripts		scripts
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
instructions.md		instructions.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts

Folders and files

Latest commit

History

Repository files navigation

Project Gorgon Data

Installation

Quick Start

Sub-path Imports

Data

Schemas

Character State

Crafting Planner

Planner Options

Plan Result

Strategies

XP Functions

Ingredient Helpers

Step Grouping

Gardening Planner

Nature Appreciation Planner

Helpers

Item Helpers

Keyword Helpers

Recipe Helpers

Build Helpers

Skill Effects

Combat Simulator

Match-3 Engine

Validation

Key Types

CraftStep

IngredientUsage

RecipeSource

IngredientNode

Development

Setup

Commands

CLI Crafting Planner

Flags

Examples

Adding a New Schema

Game Data

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages