📖 API Documentation

Overview

The ObjectStore API provides read-only access to all static game data for Grudge Warlords. This includes:

• 868 Weapons across weapon categories with tier expansion (canonical: master-weapons.json)
• 1,344 Equipment items — armor sets, gems, accessories
• 104 Materials for crafting (ore, wood, cloth, leather, gems, essences)
• 132 Consumables including foods, potions, and engineer items
• 268 Weapon Skills with icons, cooldowns, and prefab wiring
• 143 VFX Effect Sprites with frame data and blend modes
• 209 Battle Abilities with effect chains and follow-ups
• 11 Professions with skill trees and 2,183 recipes
• 19 Faction Units for RTS game mode
• 2,361 Master Items with GRUDGE UUIDs (master-items.json)
• 2,765 Registry Entries in master-registry.json
• 0 Unified Items in items-database.json (browser UI)
• 313 Animated Characters in sprite-characters.json
• 150 API Endpoints — static JSON under /api/v1/, no auth required

Base URL

https://info.grudge-studio.com/api/v1/

Docs UI: https://info.grudge-studio.com/docs. JSON endpoints are relative to /api/v1/. For example:

GET https://info.grudge-studio.com/api/v1/weapons.json
GET https://info.grudge-studio.com/api/v1/home-island-contract.json
GET https://info.grudge-studio.com/api/v1/map-registry.json

Mirror: https://molochdagod.github.io/ObjectStore/api/v1/ · CDN binaries: https://assets.grudge-studio.com/

Data Architecture — What Controls What

Icon & Asset Paths

All icon URLs in JSON data use relative paths (e.g. /icons/weapons/Sword_01.png). Each file also has a stable ICON-* UUID in icon-registry.json. Browse visually at Icon Library or resolve at runtime via grudgeSDK.resolveIconUrl().

Prefab Connection Fields

Every weapon skill has a prefab block for game engine wiring:

"prefab": {
  "modelRef": null,        // GRUDGE UUID → GLB model on R2
  "vfxRef": null,          // GRUDGE UUID → VFX effect on R2
  "impactRef": null,       // GRUDGE UUID → impact particle
  "animationClip": "2h_slash", // animation clip name
  "soundRef": null,        // GRUDGE UUID → audio on R2
  "projectileRef": null,   // GRUDGE UUID → projectile model
  "cameraShake": null      // camera shake profile
}

Fields are null until assets are created and wired. Game client skips null refs gracefully.

Authentication

No Auth Required

The ObjectStore API is completely public. No API keys, tokens, or authentication headers are needed. Simply make HTTP GET requests to any endpoint.

Creation of Truth (SSOT hierarchy)

Agents and apps must create and resolve truth from the owning source — not from previews, Puter caches, or competing hosts.

Warlords create → play funnel (only this)

id.grudge-studio.com/login?redirect_uri=https://client.grudge-studio.com/auth/callback
  → client.grudge-studio.com/home  (hub; roster from Railway)
  → empty roster: Create hero → character.grudge-studio.com (Foundry create)
  → save → return client /airship?characterId=&from=gcs
  → /home-island | /play | /tutorial | lobby with that characterId
  → definitions: ObjectStore JSON · meshes: assets CDN

Weapons Endpoint

{
  "version": "1.0.0",
  "generated": "2026-02-12T00:00:00Z",
  "categories": {
    "swords": {
      "craftedBy": "Miner",
      "category": "1h",
      "items": [
        {
          "id": "sword-bloodfeud",
          "name": "Bloodfeud Blade",
          "type": "Sword",
          "lore": "Forged in endless clan blood feuds",
          "stats": {
            "damageBase": 50,
            "damagePerTier": 12,
            "speedBase": 100,
            "critBase": 3
          },
          "basicAbility": "Vengeful Slash",
          "abilities": ["Blood Rush", "Iron Grudge", "Clan Charge"],
          "signatureAbility": "Crimson Reprisal",
          "passives": ["Bloodlust", "Swift Vengeance", "Deep Cuts"]
        }
      ]
    },
    "axes": { ... },
    "daggers": { ... },
    "spears": { ... },
    "maces": { ... },
    "hammers1h": { ... },
    "hammers2h": { ... },
    "greatswords": { ... },
    "greataxes": { ... },
    "bows": { ... },
    "crossbows": { ... },
    "guns": { ... },
    "fireStaves": { ... },
    "frostStaves": { ... },
    "holyStaves": { ... },
    "lightningStaves": { ... },
    "arcaneStaves": { ... },
    "tomes": { ... }
  }
}

Equipment Endpoint

Materials Endpoint

Armor Endpoint

Consumables Endpoint

Skills Endpoint

{
  "skills": [
    {
      "id": "vengeful-slash",
      "name": "Vengeful Slash",
      "weaponType": "Sword",
      "slot": "basic",
      "tooltip": "A fierce slash that builds Grudge Mark stacks...",
      "cooldown": 0,
      "manaCost": 0,
      "damage": "100% weapon damage",
      "effect": "Applies Grudge Mark (5% damage amp, max 3)"
    }
  ]
}

Weapon Skills Endpoint

{
  "version": "1.0.0",
  "totalSkills": 473,
  "weaponTypes": [
    {
      "weaponType": "Sword",
      "skillCount": 18,
      "skills": [
        {
          "id": "sword_vengeful_slash",
          "name": "Vengeful Slash",
          "slot": "Attack",
          "cooldown": 0,
          "manaCost": 0,
          "description": "A fierce slash dealing 100% weapon damage...",
          "effect": "Applies Grudge Mark (5% damage amp, max 3)",
          "icon": "/icons/wcs/weapons/Sword_01.png"
        }
      ]
    }
  ]
}

Professions Endpoint

Classes & Races Endpoints

Enemies & Bosses

Factions

VFX Effect Sprites

{
  "version": "1.0.0",
  "totalEffects": 147,
  "categories": ["fire", "ice", "lightning", "nature", "dark", ...],
  "effects": [
    {
      "key": "fireSpin",
      "name": "Fire Spin",
      "category": "fire",
      "frameWidth": 100,
      "frameHeight": 100,
      "cols": 8,
      "rows": 8,
      "totalFrames": 64,
      "blendMode": "screen",
      "src": "/effects/fire_spin.png"
    }
  ]
}

Battle Ability Effects

Sprite Database

Faction Units (RTS)

3D Storage & CDN Access

Grudge uses three layers for 3D content. Use the right tab/API for each — do not mix ObjectStore JSON paths with raw R2 GLB URLs.

R2 key layout (3D models)

models/characters/<name>.glb           — rigged humanoids (Mixamo / grudge6)
models/environment/island_*.glb        — home-island harvest multi-mesh packs
models/nature/organized/trees|rocks/   — extracted per-variant GLBs (no megakit)
models/nature/realistic/trees|rocks/   — catalog layout for scatter (runtime-ready)
models/biomes/review/<biome>.glb       — per-biome scale review scenes
models/evil_rock_mountain_peak_*.glb   — 20 m mountain peaks (home dungeon)
models/weapons/<name>.glb              — attachable weapon meshes
models/animations/<name>.glb           — standalone animation clips
models/buildings/<name>.glb            — structures
models/ships/enemy/{healthy,damaged,sunk}.glb
builtin/<name>.glb                     — Game Forge editor starters
catalogs/home-island/*.json            — CDN copies of island SSOT catalogs

Animation & mesh wiring

Character GLBs in models/characters/ get default animation packs in D1: glocomotion, glocomotion_combat, gestures_basic. Bone map is detected from filename/path (mixamo, bip001 for grudge6, kaykit). Weapons declare attachmentProfile (main_hand, off_hand, ranged_2h) and universal skeleton compatibility.

grudge6 race characters use FBX on CDN (not GLB) for material fidelity — see RTS-Grudge FactionCharacterRegistry. ObjectStore prefab.modelRef points at registry UUIDs; games resolve UUID → R2 URL via the asset API or icon resolver.

Upload pipeline (local → R2 → D1)

Run from RTS-Grudge after placing files or auditing Documents:

# Audit + upload + purge local copies (≤50 MB default)
npx tsx scripts/audit-documents-assets.ts --from-json scan.ndjson --upload --purge --priority

# Seed Cloudflare D1 asset_registry
npx tsx scripts/seed-d1.ts

# Bulk upload from client/public/models (fleet repo)
npx tsx scripts/upload-to-r2.ts
npx tsx scripts/seed-d1.ts

Maps & Terrain

2D tile maps and biome presets are JSON here. Full 3D arena/map GLBs (e.g. map-underground-wars) are on R2 under builtin/ and referenced in Game Forge as builtin:<key> — see 3D Storage & CDN.

Do not mix map families. Warlords era 9-sector IDs are not the home-block 3×3 IDs — see Map Families.

Map Families

Multiple 9-cell and open-world systems share the fleet. Mixing IDs causes wrong oceans, wrong zones, or broken home islands.

Home Islands

Player-owned procedural islands. Size foundations: Driftwood Bay (coast) and Ironfang Spire (highland). Both use the same physical world diameter.

Size foundations

Nature Assets (Home Island)

Organized nature for home islands. Quaternius / nature-megakit scatter props are banned at runtime.

Banned path fragments

CommonTree, TwistedTree, DeadTree, Rock_Medium, Pine_1..5 megakit, Bush_Common, nature-megakit, /models/lowpoly/

CDN layout (runtime-ready)

# Individual variants (preferred for scatter)
https://assets.grudge-studio.com/models/nature/organized/trees/{pine2_14,birch2_4,...}.glb
https://assets.grudge-studio.com/models/nature/organized/rocks/{rock_1..rock_8}.glb

# Catalog layout (same meshes, realistic/* keys)
https://assets.grudge-studio.com/models/nature/realistic/trees/pine/pine_a.glb
https://assets.grudge-studio.com/models/nature/realistic/trees/deciduous/oak_a.glb
https://assets.grudge-studio.com/models/nature/realistic/trees/palm/palm_a.glb
https://assets.grudge-studio.com/models/nature/realistic/rocks/boulder_a.glb

# Multi-mesh harvest packs (variant clone in IslandResourceLoader)
https://assets.grudge-studio.com/models/environment/island_tree.glb
https://assets.grudge-studio.com/models/environment/island_rock.glb
https://assets.grudge-studio.com/models/environment/gem_cluster.glb

npm run home-island:pipeline          # export → biome reviews → SSOT → R2 upload → CDN probe
npm run home-island:export-nature     # pack → organized + realistic GLBs
npm run home-island:upload            # R2 put (skip if size matches)

Biome Ecosystems

One truth for what each biome offers: 5 land animals, 10 fish species pool, tree class policy, 20 m mountain peak, 4 h harvest regen, character reference 2.0 m.

Review scenes include 20 m peak scale markers and a 2 m character capsule for visual QA.

Freeform ARPG (Characters)

Warlords is freeform: race = body mesh, equipment = weapons/armor/anims, class is flavor only (not a hard gear lock).

• Character mesh pipeline: loadCharacterModel + equipment slots + appearance tint (sRGB multiply from base, no stack).
• Unlock tables no longer gate weapons by rigid class.
• See warlords-catalog.json characterTruth and warlords-zones.json freeform notes.

Production Wiring (Characters · Accounts · Crafting)

Industry-standard multi-app identity: one Grudge ID account, many character UUIDs, shared account bag, per-character progression. Full agent skill: grudge-production-wiring. Creation hierarchy: Creation of Truth.

Scope matrix

Crafting site flow

grudge-crafting.puter.site
  → id.grudge-studio.com/login?redirect_uri=…puter.site…
  → Bearer JWT
  → Railway GET /api/characters
  → craft: account bag − materials · character progress + XP (revisioned)
  → ObjectStore master-recipes.json / professions.json for definitions
  → assets.grudge-studio.com icons + grudge-fleet.js

Warlords Catalog & Zones

Animations

animations.json defines clip names, blend rules, and state-machine wiring. Actual Mixamo / combat GLB clips live on R2 at models/animations/*.glb and are indexed in D1 — see 3D Storage & CDN.

AI Systems

Tier System

All equipment in Grudge Warlords uses an 8-tier system:

Stats scale with tier using base + (perTier × (tier - 1))

Items Database

{
  "version": "1.0.0",
  "totalItems": 3425,
  "categories": ["weapons", "armor", "consumables", "materials", "accessories", "relics", "capes", "shields"],
  "items": [
    {
      "id": "sword-bloodfeud-t5",
      "name": "Bloodfeud Blade",
      "category": "weapons",
      "type": "Sword",
      "tier": 5,
      "icon": "/icons/weapons/Sword_01.png",
      "tooltip": "Forged in endless clan blood feuds",
      "stats": { "damage": 98, "speed": 100 }
    }
  ]
}

Sprite Characters

{
  "version": "2.0.0",
  "totalCharacters": 275,
  "characters": [
    {
      "id": "warrior_male",
      "name": "Warrior Male",
      "source": "RPG-MODULAR",
      "animations": {
        "idle":   { "src": "/sprites/Warrior/Idle.png",   "cols": 8, "rows": 1 },
        "walk":   { "src": "/sprites/Warrior/Walk.png",   "cols": 8, "rows": 1 },
        "attack": { "src": "/sprites/Warrior/Attack.png", "cols": 6, "rows": 1 }
      }
    }
  ]
}

grudgeDot Assets

{
  "version": "1.0.0",
  "totalAliases": 25,
  "aliases": [
    { "heroClass": "warrior", "race": "human", "spriteId": "warrior_male", "src": "/sprites/Warrior/Idle.png" }
  ]
}

Voxel Assets

Asset Registries

JSON catalogs for 2D icons, sprites, VFX, and UI. For live 3D GLB binaries use 3D Storage & CDN (assets.grudge-studio.com + api.grudge-studio.com/assets) — not this section.

RTS Models

Two registries serve RTS 3D content — use both, for different purposes:

• ObjectStore /api/v1/rtsModels.json — design-time paths and prefab wiring for the RTS game mode.
• Live D1 + R2 api.grudge-studio.com/assets — production GLB binaries on CDN with searchable metadata (category, bone map, animation packs).

Worlds

AI Sprite Editor

The 2D Models Browser includes a built-in AI sprite editing assistant powered by Puter.js.

Available AI Commands

Sprite Uploader & Parser

Upload and parse sprite sheets, GIFs, individual PNGs, and Aseprite atlas exports. Available via the 📤 Upload Sprites button in the 2D Models Browser toolbar.

Puter.js Integration

The ObjectStore uses Puter.js v2 for free, serverless AI and cloud storage — no API keys or backend needed.

APIs Used

JavaScript SDK v5.0

Single import for all backend services + static game data:

// CDN
import { GrudgeSDK } from 'https://objectstore.grudge-studio.com/sdk/grudge-sdk.js';

// or NPM
// npm install @grudgstudio/core
import { GrudgeSDK } from '@grudgstudio/core';

const sdk = new GrudgeSDK({ token: '<JWT>' });

// Static game data
const weapons = await sdk.getWeapons();
const swords  = await sdk.getWeaponsByCategory('swords');
const items   = await sdk.getItemsDatabase();   // 3,425 items
const chars   = await sdk.getSpriteCharacters(); // 275 animated chars
const results = await sdk.search('iron');

// Tier colors
const t5 = GrudgeSDK.getTierColor(5); // { name: 'Red', hex: '#ff4d4d', label: 'Legendary' }

Backend Service Clients (SDK v5.0)

Authenticated clients for live fleet services. Prefer Railway + ID + CDN over legacy hostnames.

Legacy names api.grudge-studio.com, assets-api.grudge-studio.com, ws.grudge-studio.com are not player-state SSOT. Use Railway + CDN paths above.

const sdk = new GrudgeSDK({ token: '<JWT>' });

// Auth
const res  = await sdk.auth.login('username', 'password');
const me   = await sdk.auth.getMe();

// Game API
const chars   = await sdk.game.listCharacters();
const balance = await sdk.game.getBalance(charId);
await sdk.game.startCraft({ char_id: 1, recipe_key: 'iron-sword' });

// Account
const profile = await sdk.account.getProfile(grudgeId);
const friends = await sdk.account.listFriends();

// Asset Service (R2)
const assets = await sdk.assets.listAssets({ prefix: 'models/' });

// WebSocket
const socket = sdk.ws.game();
socket.emit('join-island', { island_key: 'island_1' });

Python Examples

import requests

BASE_URL = "https://objectstore.grudge-studio.com/api/v1"

# Get all weapons
weapons = requests.get(f"{BASE_URL}/weapons.json").json()

# Find all swords
swords = weapons["categories"]["swords"]["items"]
print(f"Found {len(swords)} swords")

# Get materials
materials = requests.get(f"{BASE_URL}/materials.json").json()

# Find T5+ ores
high_tier_ores = [m for m in materials["materials"] 
                  if m["category"] == "ore" and m["tier"] >= 5]

Search API (Serverless)

GET /api/search?q=iron&type=materials&limit=10

{
  "query": "iron",
  "type": "materials",
  "totalResults": 3,
  "results": [
    { "type": "material", "id": "iron-ore", "name": "Iron Ore", "category": "ore", "tier": 2 },
    { "type": "material", "id": "iron-ingot", "name": "Iron Ingot", "category": "ingot", "tier": 2 }
  ]
}

Stats API (Serverless)

AI Integration

The ObjectStore API is designed for AI agent consumption:

• No Authentication - Direct HTTP access
• JSON Format - Easy to parse
• Stable Schema - Rarely changes
• Complete Data - All game definitions in one place

Example: AI Crafting Assistant

// Fetch required data
const [weapons, materials] = await Promise.all([
  fetch(BASE_URL + '/weapons.json').then(r => r.json()),
  fetch(BASE_URL + '/materials.json').then(r => r.json())
]);

// Helper: Get materials needed for a weapon
function getCraftingRequirements(weaponId, tier) {
  const weapon = findWeapon(weapons, weaponId);
  const tierMaterials = materials.materials.filter(m => m.tier === tier);
  
  return {
    weapon: weapon.name,
    tier: tier,
    profession: weapon.craftedBy,
    primaryMaterial: tierMaterials.find(m => 
      m.gatheredBy === weapon.craftedBy
    )
  };
}