📖 API Documentation

Weapon Passive Stacks

{
  "id": "grudge_mark",
  "name": "Grudge Mark",
  "applyCondition": "on_hit",
  "effect": {
    "amplification": 0.05
  },
  "maxStacks": 3,
  "duration": null,
  "weaponTypes": ["sword", "axe"],
  "sources": {
    "design": "api/v1/weapons.json:34",
    "runtime": "NOT_IMPLEMENTED"
  }
}

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)

asset-packs/toon-rts-characters/glb/characters/{race}.glb — play kits (loadRaceKit)
prod/anims/<pack>/                     — Bip001 idle/walk/cast/melee
models/characters/<name>.glb           — other rigged humanoids (not Warlords play default)
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.

Play heroes use Toon RTS {race}.glb via ObjectStore js/grudge6-kit.js loadRaceKit only. FBX race kits are the Unity author source — not the play default. RTS-Grudge FactionCharacterRegistry is example-tool code, not the Warlords play loader. ObjectStore prefab.modelRef points at registry UUIDs; games resolve UUID → R2 URL via CDN, not D1 as the file server.

Upload pipeline (local → R2 → D1 index)

Bake with ObjectStore npm run convert, then upload to R2. D1 is the search index only. Prefer GrudgeBuilder scripts/upload-*-to-r2.mjs for new Warlords meshes. Legacy RTS-Grudge seed scripts still exist for the old asset-api Worker:

# 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

Island Build Doctrine

Canonical 1 m occupy grid, faction kits, NPC execution order, HUD, dock crew, and honest asset gaps. Play client executes this contract. Definitions: ObjectStore. Binaries: R2. Island seed: Railway home_islands.

ISLAND-BUILD-DOCTRINE.md · machine JSON below.

Build phases (NPC order)

Claim flag → harvest → plaza → walls/gates → paths → outposts → lots → profession RTS → defense. One host pack. No mixed-faction mashups. No dummy benches.

Dock crew (hubs only)

Sailor · Weatherman · Gunner — race of the captain, grudge6 kit @ 0.9. Planted on the dock / outpost zone, not inside the curtain.

Nature runtime

Kenney CommonTree / Pine_1 / Rock_Medium / Bush_Common are author-only. Play loads organized stems + R2 island_tree.glb / island_rock.glb / palm isolate M_Palm_P2_*.

Nature Assets (Home Island)

Organized nature for home islands. Quaternius / nature-megakit scatter props are banned at runtime. The Warlords play client loads stylized-tree, stone-black, realistic-palms, and R2 harvest packs — never Kenney CommonTree / Pine_1 / Rock_Medium / Bush_Common.

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 1.8 m human (orc ~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

Era systems API

Four product eras. One Grudge ID. Roster is GET /api/characters?era=. Machine: /api/v1/era-systems.json. Human: ERA_SYSTEMS_API.md. UI slots: ui.grudge-studio.com/api/eras.

Open launcher (library + account into games)

open.grudge-studio.com is the Steam-like library and Grudge ID hub — not Warlords play, not GRUDOX cabinets, not Foundry. Machine: /api/v1/open-launcher.json. Human: OPEN_LAUNCHER_API.md.

Same-origin open…/api/* → Railway. JWT keys: grudge.open.token, sso_token. Engine keeps Controller / weapon / camera on map change; rebind terrain only. Handoff: ?characterId=&era=.

Prefab · asset update scheme

One pattern for agents. Machine: /api/v1/prefab-scheme.json. Human: PREFAB_ASSET_SCHEME.md.

Skill/item prefab block: modelRef · vfxRef · animationClip = {pack}/{role} on Bip001. Null refs are valid. Play Warlords body = Toon {race}.glb via loadRaceKit.

UUID law

Wiki: wiki.html. Machine: /api/v1/uuid-law.json. Account contract: account-game-uuid-contract.json.

Editors · Prefabs · Stack · Scripts

Correct wiring for agents. Machine JSON: /api/v1/fleet-wiring.json. Do not invent a second editor, loader, bag DB, or npm stack.

Editors (do not collapse brands)

Prefabs

Play CDN: https://assets.grudge-studio.com/asset-packs/toon-rts-characters/glb/characters/{race}.glb

Stack dependencies (do not add a second)

Ban: second mixer, second physics engine, Meshy/capsule as play hero, OrbitControls writing combat TPS camera. Full matrix: skill grudge-3d-game-packages · Open docs/OPEN_PACKAGE_SSOT.md.

ObjectStore scripts

cd F:\GitHub\ObjectStore
npm run sync:docs                 # this /docs page + canonical-manifest
npm run convert                   # production GLB bake → then R2
npm run wire:skill-prefab-anims   # prefab.animationClip pack/role
npx vercel --prod                 # info.grudge-studio.com + objectstore.grudge-studio.com

API · D1 · Deploy (do not mix stores)

ObjectStore is definitions. D1 is an index. Railway is player state. R2 is binaries. Mixing those is how catalogs and heroes go stale.

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
    )
  };
}