Version 5.1.0 | Unified Game Data API, Backend SDK & Integration Hub
The complete data backbone for all Grudge Studio projects โ 45+ JSON API endpoints, 13,000+ game assets, full backend SDK for all VPS services, and game data extracted from GrudgeWars.
Live API: molochdagod.github.io/ObjectStore ยท Game: grudgewarlords.com ยท Wiki: GitHub Wiki ยท Agent Context: AGENT-CONTEXT.md
npm install @grudgstudio/coreimport { initGrudgeStudio } from '@grudgstudio/core';
const api = await initGrudgeStudio({
objectStoreUrl: 'https://molochdagod.github.io/ObjectStore',
puterEnabled: true, // Enable AI image generation
aiBackendUrl: 'http://localhost:3000/api/ai', // AI agents backend
gameApiUrl: 'http://localhost:4000/api/gruda' // GAME_API_GRUDA
});
// Search for T5 swords
const items = await api.search('sword', { tier: 5 });
// Create item with GRUDGE UUID
const item = api.createItem({
type: 'weapon',
name: 'Legendary Blade',
tier: 8
});
console.log(item.uuid); // ITEM-20260225120000-000001-A1B2C3D4
// Use AI agents
const lore = await api.ai.generateLore({ item: 'Legendary Blade' });
const balanced = await api.ai.balanceItem(item);๐ Full Integration Guide | ๐ง Unity C# Example | โ๏ธ React/TS Example
All frontend assets from grudgewarlords.com (Grudge-Builder) are now served from ObjectStore:
- 3,024 files migrated (~306 MB) โ icons, sprites, backgrounds, UI, portraits, professions
- 13,000+ total assets across all categories
- Frontend uses
assetUrl()helper pointing tohttps://molochdagod.github.io/ObjectStore - New folders:
images/events/,images/portraits/,images/professions/,images/ui/,images/misc/,images/lore/,sprites/pirate/ - CORS headers updated for all new asset paths
- 208 animated characters with 2,388 unique 2D sprites across 3 sources
- 47 fish species from Grudge Angeler with full sprite sheets
- 25 grudgeDot Assistant hero aliases mapped to existing sprites
- 7,400+ icons across weapons, armor, food, materials, RPG packs, entities, potions, resources
- 450 audio files (SFX in wav/mp3/ogg/flac)
- 471 3D model registry (GLB, GLTF, FBX, OBJ) organized by race
- 170+ backgrounds, 36 hero portraits, 6 cinematic videos
- 12 new JSON API endpoints extracted from GrudgeWars source:
- Quests (28 zones), Missions (10 story + 10 arena), Skill Trees (4 classes)
- Equipment (15 weapon types + skills), Enemy Templates (20+ types, 8 bosses)
- World Map (33 locations, 79 paths), Dialogue (7 trigger types, 6 races)
- Cutscenes, Regions, Battle Formations, Random Events, Lore (3 gods + heroes)
- MCP Server with 7 tools for AI agent integration
- OpenAPI 3.0.3 spec covering all 45+ endpoints
- Service Worker with stale-while-revalidate caching
- Vercel serverless endpoints (search, stats, export)
- SDK with 30+ methods covering every endpoint
- CI workflow for auto-regenerating registries
- JSON schema validation for 14+ data files
- Changelog/RSS generation from git log
Base URL: https://molochdagod.github.io/ObjectStore
| Endpoint | Description |
|---|---|
/api/v1/weapons.json |
All weapons (17 categories ร 6 weapons ร 8 tiers = 816 items) |
/api/v1/materials.json |
Crafting materials (ore, wood, cloth, leather, gems, essence) |
/api/v1/armor.json |
Armor slots (helm, chest, boots, etc.) |
/api/v1/consumables.json |
Potions, bandages, grenades |
/api/v1/skills.json |
Weapon skill trees (sword, axe, bow, staff, gun) |
/api/v1/professions.json |
Profession definitions and metadata |
/api/v1/races.json |
6 playable races with bonuses, lore, and faction affiliations |
/api/v1/classes.json |
4 classes with abilities, weapon/armor types, and signature moves |
/api/v1/factions.json |
3 factions (Crusade, Legion, Fabled) with race mappings |
/api/v1/attributes.json |
8 attribute definitions with stat formulas |
/api/v1/quests.json |
Zone quests (28 zones, 112 quests) |
/api/v1/missions.json |
Story missions + arena templates |
/api/v1/skillTrees.json |
Full skill trees (4 classes, 5 tiers each) |
/api/v1/equipment.json |
Equipment types, tiers, weapon skills |
/api/v1/enemyTemplates.json |
20+ enemy types with abilities, 8+ bosses |
/api/v1/worldMap.json |
33 locations, 79 paths, terrain regions |
/api/v1/dialogue.json |
NPC dialogue, race/class chatter |
/api/v1/cutscenes.json |
Zone intro cutscenes + extended lore |
/api/v1/regions.json |
5 world regions with zone mappings |
/api/v1/battleFormations.json |
Player/enemy row formations |
/api/v1/randomEvents.json |
8 random event templates |
/api/v1/lore.json |
3 gods + hero lore entries |
/api/v1/audio.json |
450 sound effect registry |
/api/v1/video.json |
6 cinematic video registry |
/api/v1/heroes.json |
36 hero portrait + effect images |
/api/v1/models3d.json |
471 3D model registry (GLB/GLTF/FBX/OBJ) |
/api/v1/ai.json |
AI agent configuration and prompts |
/api/v1/animations.json |
Animation definitions |
/api/v1/asset-registry.json |
Master asset registry |
/api/v1/controllers.json |
Controller configurations |
/api/v1/ecs.json |
Entity Component System definitions |
/api/v1/nodeUpgrades.json |
Node upgrade paths |
/api/v1/rendering.json |
Rendering configuration |
/api/v1/rtsModels.json |
RTS model registry |
/api/v1/spriteMaps.json |
Sprite map definitions |
/api/v1/sprite-characters.json |
275 animated characters with animations, grid/frame-sequence support |
/api/v1/sprites2d.json |
2,388 unique 2D sprites (flat registry) |
/api/v1/grudgedot-hero-aliases.json |
25 hero class โ sprite mappings for grudgeDot Assistant |
/api/v1/items-database.json |
Unified item database โ 3,425 items with icon URLs, stats, tooltips (8 categories) |
/api/v1/terrain.json |
Terrain configuration |
/api/v1/tileMaps.json |
Tile map definitions |
ObjectStore integrates with all Grudge Studio repositories:
- Warlord-Crafting-Suite โ React/TypeScript crafting system with Arsenal tab
- GrudgeWarlords โ Unity WebGL MMO with real-time item loading
- GrudgeStudioNPM โ NPM package aggregator for all Grudge modules
- Grudge Crafting (Puter) โ Puter-hosted crafting suite, fetches items-database.json for Item Database tab and real icons
- grudge-warlords โ Voxel RPG with ItemRegistry integration
- PuterGrudge โ Backend server with AI image generation endpoints
- GrudgeGameIslands โ WebGL island exploration with materials system
35+ repositories including: grudge-match-webgl, grudge-angeler, nexus-webgl, TheForge, Grudge-Realms, GrudgeController, and more.
See Integration Guide for complete implementation examples.
The Grudge SDK provides a single import for all backend services + static game data.
import { GrudgeSDK } from 'https://molochdagod.github.io/ObjectStore/sdk/grudge-sdk.js';
const sdk = new GrudgeSDK({ token: '<JWT>' });
// โโ Static game data (ObjectStore) โโ
const weapons = await sdk.getWeapons();
const swords = await sdk.getWeaponsByCategory('swords');
const results = await sdk.search('iron');
const iconUrl = sdk.getWeaponIconUrl('swords', 0, 5);
// โโ Auth (id.grudge-studio.com) โโ
const res = await sdk.auth.login('user', 'pass');
const me = await sdk.auth.getMe();
// โโ Game API (api.grudge-studio.com) โโ
const chars = await sdk.game.listCharacters();
const balance = await sdk.game.getBalance(charId);
await sdk.game.startCraft({ char_id: 1, recipe_key: 'iron-sword' });
const lobbies = await sdk.game.listLobbies({ mode: 'duel' });
// โโ Account API (account.grudge-studio.com) โโ
const profile = await sdk.account.getProfile(grudgeId);
const friends = await sdk.account.listFriends();
// โโ Launcher API (launcher.grudge-studio.com) โโ
const manifest = await sdk.launcher.getManifest();
// โโ Asset Service (assets-api.grudge-studio.com) โโ
const assets = await sdk.assets.listAssets({ prefix: 'models/' });
// โโ WebSocket (ws.grudge-studio.com) โโ
const gameSocket = sdk.ws.game();
gameSocket.emit('join-island', { island_key: 'island_1' });
// โโ Tier colors (D5 labels) โโ
const t5 = GrudgeSDK.getTierColor(5); // { name: 'Red', hex: '#ff4d4d', label: 'Heroic' }
const t8 = GrudgeSDK.getTierColor(8); // { name: 'Shimmer', hex: '#f0d890', label: 'Legendary' }| Client | URL | Description |
|---|---|---|
sdk.auth |
id.grudge-studio.com | Login, register, guest, wallet, discord, puter, identity |
sdk.game |
api.grudge-studio.com | Characters, economy, crafting, combat, PvP, islands, missions, crews, inventory, gouldstones, AI |
sdk.account |
account.grudge-studio.com | Profiles, friends, notifications, achievements, sessions |
sdk.launcher |
launcher.grudge-studio.com | Manifest, entitlements, version history |
sdk.assets |
assets-api.grudge-studio.com | Upload, list, delete assets |
sdk.ws |
ws.grudge-studio.com | Socket.IO namespaces: /game, /crew, /global, /pvp |
sdk.ai |
ai.grudge-studio.com | AI worker โ generate sprites/icons, auto-tag, semantic search, game agents |
sdk.r2 |
objectstore.grudge-studio.com | R2 storage (3D models, shaders, 3DFX) |
Endpoint: https://ai.grudge-studio.com
The AI Worker runs on Cloudflare's edge with Workers AI, sharing the same R2 bucket and D1 database as the ObjectStore API. It provides:
- Sprite generation โ text-to-sprite via Stable Diffusion XL
- Icon generation โ tier-aware RPG item icons
- Asset description โ image-to-text for any R2 asset
- Auto-tagging โ AI-powered tag suggestions for assets
- Semantic search โ query expansion + keyword matching across all assets
- Game agents โ 6 specialized agents (lore, balance, code, art, mission, QA)
import { GrudgeSDK } from './sdk/grudge-sdk.js';
const sdk = new GrudgeSDK({ token: '<JWT>' });
// Generate a sprite
const sprite = await sdk.ai.generateSprite('orc warrior with axe', { style: '32x32 RPG character' });
console.log(sprite.image); // data:image/png;base64,...
console.log(sprite.asset); // { id, key, url } โ auto-saved to R2
// Generate a tier-5 weapon icon
const icon = await sdk.ai.generateIcon('flaming greatsword', { tier: 5, category: 'weapon' });
// Auto-tag an existing asset
const tags = await sdk.ai.tag('asset-uuid-here');
// Semantic search
const results = await sdk.ai.search('fire spell effects', { category: 'effects' });
// Chat with game agents
const lore = await sdk.ai.chat('Create a backstory for the Crusade faction', { agent: 'lore' });
const balance = await sdk.ai.chat('Is T5 sword damage balanced vs T5 axe?', { agent: 'balance' });# Run D1 migration (one-time)
wrangler d1 execute objectstore-meta --file=workers/ai/schema.sql
# Deploy
wrangler deploy --config workers/ai/wrangler.toml
# Local dev
wrangler dev --config workers/ai/wrangler.tomlNEW in 2.1.0: Integrated AI agent system with specialized agents for game development.
- Code Agent: Code generation, refactoring, optimization
- Art Agent: Asset generation, style guidance, icon design
- Lore Agent: World building, narrative consistency, character backstories
- Balance Agent: Game balance analysis, stat tuning, economy balance
- QA Agent: Test strategies, bug detection, edge case analysis
- Mission Agent: Quest design, mission flow, reward structures
import { initGrudgeStudio } from '@grudgstudio/core';
const api = await initGrudgeStudio({
aiBackendUrl: 'http://localhost:3000/api/ai'
});
// Query an AI agent
const response = await api.ai.queryAgent({
agentType: 'lore',
prompt: 'Create a backstory for a legendary sword',
context: { faction: 'Crusade', tier: 8 }
});
console.log(response.result);
// Research game balance
const research = await api.ai.research({
topic: 'T8 weapon damage scaling',
category: 'balance',
context: { currentMax: 500, proposedMax: 650 }
});
// Design a mission
const mission = await api.ai.designMission({
level: 50,
type: 'boss-raid',
faction: 'Legion',
rewards: ['epic-weapon', 'gold']
});
// Connect to GAME_API_GRUDA (local IDE integration)
const result = await api.ai.connectToGameAPI('update-character', {
characterId: 'hero-123',
stats: { strength: 100 }
});If the AI backend is unavailable, the system automatically falls back to Puter.js:
// Works offline with Puter fallback
const api = await initGrudgeStudio({ puterEnabled: true });
const lore = await api.ai.generateLore({ item: 'Mystic Staff' });Full TypeScript definitions included:
import type { AIRequest, AIResponse, ResearchQuery } from '@grudgstudio/core';
const request: AIRequest = {
agentType: 'balance',
prompt: 'Analyze this weapon',
context: { weapon: myWeapon }
};- Game definitions (what items/races/classes exist)
- No authentication required
- Hosted on GitHub Pages (free CDN)
For player-specific data, economy, PvP, and accounts โ self-hosted Docker + Coolify on VPS:
| Service | URL | Description |
|---|---|---|
| Identity / Auth | id.grudge-studio.com |
JWT auth (Discord, Web3Auth, Puter, guest, wallet) |
| Game API | api.grudge-studio.com |
Characters, economy, crafting, combat, PvP, islands, missions, crews |
| Account API | account.grudge-studio.com |
Profiles, friends, notifications, achievements |
| Launcher API | launcher.grudge-studio.com |
Version manifest, entitlements, launch tokens |
| WebSocket | ws.grudge-studio.com |
Real-time events (Socket.IO: /game, /crew, /global, /pvp) |
| Asset Service | assets-api.grudge-studio.com |
Upload/manage assets (metadata + conversions) |
| R2 CDN | assets.grudge-studio.com |
Public asset delivery (Cloudflare R2 Worker) |
| Dashboard | dash.grudge-studio.com |
Admin dashboard (Cloudflare Worker) |
| Status | status.grudge-studio.com |
Uptime monitoring (Uptime Kuma) |
See grudge-studio-backend GRUDGE-STUDIO-CONTEXT.md for full reference.
{
"categories": {
"swords": {
"iconBase": "Sword",
"iconMax": 40,
"items": [
{
"id": "bloodfeud-blade",
"name": "Bloodfeud Blade",
"primaryStat": "damage",
"secondaryStat": "lifesteal",
"emoji": "โ๏ธ"
}
]
}
}
}{
"categories": {
"ore": {
"items": [
{
"id": "iron-ore",
"name": "Iron Ore",
"tier": 2,
"gatheredBy": "Miner",
"emoji": "โ๏ธ"
}
]
}
}
}All items display real icon assets โ no emoji or placeholder images.
- Weapons: Named icons at
/icons/weapons/{id}.png(e.g.bloodfeud-blade.png), with automatic fallback to/icons/wcs/weapons/{Type}_{##}.pngpack (502 real weapon sprites) - Armor:
/icons/pack/armor/{Slot}_{##}.png(Helm, Chest, Boots, Gloves, etc.) - Materials: Named icons at
/icons/materials/{id}.pngwith category-matched fallback - Consumables: Smart matching โ 18 food icons, 10 herb icons, 48 potion icons, 48 alchemy icons
- Tools: Mapped to appropriate weapon-type icons (pickโhammer, axeโaxe, knifeโdagger)
/icons/weapons/โ 82 named weapon icons/icons/wcs/weapons/โ 502 weapon sprites (Sword, Axe, Dagger, Hammer, Spear, Bow, etc.)/icons/pack/armor/โ Armor slot icons (Helm, Chest, Boots, Belt, Ring, etc.)/icons/consumables/โ Food, herbs, potions, alchemy items/icons/materials/โ 79 crafting material icons/icons/skills/โ Class-based skill icons (aeromancer, pirate, swordsman, warlock)/icons/abilities/โ 28 ability icons/icons/spells/โ Spell effect icons with color variants
Live: molochdagod.github.io/ObjectStore/2D_MODELS.html
Full-featured sprite browser, editor, and validation tool with:
- Canvas animation โ horizontal, vertical, grid, and frame-sequence layouts
- Sprite editor โ Hue/Saturation/Brightness sliders, horizontal flip, auto-trim transparent padding
- VFX preview โ Additive/Screen/Multiply blending modes, Dark/Light/Checkerboard backgrounds, Loop/Ping-pong/Once playback
- Export โ Single frame or all frames as individual PNGs (with edits applied)
- Validation report โ Tests every sprite for broken images, frame size mismatches, and missing animations
- 275 characters, 2,220 animations across 10 categories (characters, enemies, bosses, monsters, effects, fish, npcs, companions, projectiles, ui)
- rpg-modular โ Core RPG character/enemy/boss/effect sprites
- grudge-angeler โ 48 fish species with animated sprite sheets from Grudge Angeler
- objectstore โ Additional sprites from effects, UI, projectiles, companions, and other packs
// Fetch all animated characters
const res = await fetch('https://molochdagod.github.io/ObjectStore/api/v1/sprite-characters.json');
const data = await res.json();
// data.characters[0] = { name, category, source, uuid, animations: [...] }
// Each animation has: uuid, id, name, path, width, height, frameCount, frameW, frameH, layout, cols, rows
// Filter by category
const effects = data.characters.filter(c => c.category === 'effects');
const bosses = data.characters.filter(c => c.category === 'bosses');node tools/scan-sprites.js # Scan sprites/ directory and regenerate sprite-characters.jsonThe scanner reads PNG headers directly (no external deps), auto-detects frame layouts, deduplicates flat/nested paths, and preserves existing UUIDs.
ObjectStore/
โโโ api/v1/ # 49+ Static JSON API endpoints
โ โโโ weapons.json # 17 categories, 816+ items
โ โโโ armor.json # Helm, chest, boots, etc.
โ โโโ materials.json # Ore, wood, cloth, leather, gems
โ โโโ sprite-characters.json # 275 animated characters (3 sources)
โ โโโ sprites2d.json # 2,220+ animations across all sprites
โ โโโ items-database.json # 3,425 items with icons, stats, categories
โ โโโ grudgedot-hero-aliases.json # Hero class โ sprite mappings
โ โโโ quests.json # 28 zones, 112 quests
โ โโโ missions.json # Story + arena templates
โ โโโ skillTrees.json # 4 classes ร 5 tiers
โ โโโ equipment.json # Weapon types + skills
โ โโโ enemyTemplates.json # 20+ enemies, 8+ bosses
โ โโโ worldMap.json # 33 locations, 79 paths
โ โโโ dialogue.json # NPC chatter system
โ โโโ cutscenes.json # Zone intro cinematics
โ โโโ audio.json # 450 SFX registry
โ โโโ video.json # 6 cinematic videos
โ โโโ heroes.json # 36 hero portraits
โ โโโ models3d.json # 471 3D model registry
โ โโโ ... # + 30 more endpoints
โโโ sprites/ # 275 characters, 2,220+ animations, 3,500+ PNGs
โ โโโ characters/ # Player characters (55 dirs)
โ โโโ enemies/ # Enemy units
โ โโโ bosses/ # Boss encounters
โ โโโ monsters/ # Monster creatures
โ โโโ fish/ # 47 Angeler fish species + generic
โ โโโ effects/ # VFX sprite sheets
โ โโโ ... # npcs, companions, projectiles, ui
โโโ icons/ # 5,653 PNG icons
โโโ backgrounds/ # 167 scene backgrounds
โโโ heroes/ # 36 hero portraits + effects
โโโ audio/ # 450 SFX (wav/mp3/ogg/flac)
โโโ video/ # 6 cinematic MP4s
โโโ branding/ # Favicons + brand assets
โโโ sdk/grudge-sdk.js # SDK v5.0 โ unified client for all services
โโโ mcp/ # MCP server for AI agents
โโโ scripts/ # Build + extraction tools
โ โโโ build-items-json.js # Parse GRUDGE_Item_Database.html โ items-database.json
โโโ tools/ # Sprite tools
โ โโโ scan-sprites.js # Walk sprites/, auto-detect layouts, regenerate JSON
โโโ workers/ai/ # AI Worker (Cloudflare Workers AI)
โ โโโ index.js # AI endpoints (generate, tag, search, chat)
โ โโโ wrangler.toml # Config (R2 + D1 + AI bindings)
โ โโโ schema.sql # D1 migration for ai_jobs table
โโโ openapi.yaml # OpenAPI 3.0.3 spec
โโโ sw.js # Service worker
โโโ package.json # @grudge-studio/objectstore v3.0.0
โโโ README.md
This repository is deployed automatically:
- Push to
mainbranch - GitHub Actions builds and deploys
- Available at
https://molochdagod.github.io/ObjectStore - API Docs:
https://molochdagod.github.io/ObjectStore/docs/
Publish @grudge-studio/core to NPM:
cd D:\GrudgeLink\OneDrive\Desktop\ObjectStore
npm login
npm publish --access publicUpdate version:
npm version patch # 2.1.0 -> 2.1.1
npm version minor # 2.1.0 -> 2.2.0
npm version major # 2.1.0 -> 3.0.0See WIKI-DEPLOYMENT.md for full deployment guide.
ยฉ 2026 Grudge Studio. Game data provided for use with Grudge Studio applications.