Eve library

Gameplay API

Guide

Revision 1

On this page

Game mechanics, physics systems, combat, and interactive gameplay features.

Overview#

The Gameplay API provides endpoints for implementing core game mechanics including combat systems, physics simulation, inventory management, quest systems, and AI-driven NPC behavior.

Base Path: /v1/gameplay

Authentication: Bearer token required

Endpoints Summary#

Method Path Description
POST /combat/simulate Simulate combat encounter
POST /combat/calculate-damage Calculate damage values
GET /combat/stats/{characterId} Get combat statistics
POST /physics/simulate Run physics simulation
POST /physics/raycast Perform raycast query
POST /physics/collision Check collision detection
POST /inventory/create Create inventory system
POST /inventory/{inventoryId}/add Add item to inventory
POST /inventory/{inventoryId}/remove Remove item
POST /inventory/{inventoryId}/transfer Transfer between inventories
POST /quest/create Create quest
POST /quest/{questId}/update Update quest progress
GET /quest/{questId}/status Get quest status
POST /dialogue/generate Generate dialogue options
POST /dialogue/respond Process dialogue response
POST /economy/transaction Process economic transaction
GET /economy/balance Get currency balance
POST /crafting/recipe Check crafting recipe
POST /crafting/craft Craft item

Combat System#

Simulate Combat#

Run a combat simulation between entities.

http
POST /v1/gameplay/combat/simulate
Authorization: Bearer <token>
Content-Type: application/json

{
  "combatType": "turn_based",
  "participants": [
    {
      "id": "player_001",
      "team": "player",
      "stats": {
        "health": 100,
        "attack": 25,
        "defense": 15,
        "speed": 20,
        "critChance": 0.1,
        "critMultiplier": 1.5
      },
      "abilities": ["slash", "shield_bash", "heal"],
      "equipment": {
        "weapon": "sword_iron",
        "armor": "plate_steel"
      }
    },
    {
      "id": "enemy_goblin_01",
      "team": "enemy",
      "stats": {
        "health": 50,
        "attack": 15,
        "defense": 5,
        "speed": 25
      },
      "abilities": ["scratch", "dodge"],
      "ai": "aggressive"
    }
  ],
  "rules": {
    "turnOrder": "speed",
    "maxTurns": 100,
    "allowFleeing": true
  },
  "environment": {
    "terrain": "dungeon",
    "lighting": "dim",
    "hazards": ["pit_trap"]
  }
}

Combat Types:

Type Description
turn_based Traditional turn-based combat
real_time Real-time combat simulation
action Action RPG style
tactical Tactical grid-based
auto_battle Automatic battle resolution

Response:

json
{
  "success": true,
  "data": {
    "result": "victory",
    "winner": "player",
    "turns": 8,
    "duration": 45.5,
    "combatLog": [
      {
        "turn": 1,
        "actor": "enemy_goblin_01",
        "action": "scratch",
        "target": "player_001",
        "damage": 12,
        "effects": []
      },
      {
        "turn": 1,
        "actor": "player_001",
        "action": "slash",
        "target": "enemy_goblin_01",
        "damage": 28,
        "effects": ["bleeding"]
      }
    ],
    "finalState": {
      "player_001": { "health": 76, "status": "alive" },
      "enemy_goblin_01": { "health": 0, "status": "defeated" }
    },
    "rewards": {
      "experience": 150,
      "gold": 25,
      "items": ["goblin_ear", "rusty_dagger"]
    },
    "statistics": {
      "damageDealt": { "player_001": 128 },
      "damageTaken": { "player_001": 24 },
      "criticalHits": 2,
      "abilitiesUsed": 5
    }
  }
}

Calculate Damage#

Calculate damage for an attack.

http
POST /v1/gameplay/combat/calculate-damage
Authorization: Bearer <token>
Content-Type: application/json

{
  "attacker": {
    "attack": 50,
    "weaponDamage": { "min": 10, "max": 20 },
    "critChance": 0.15,
    "critMultiplier": 2.0,
    "bonuses": [
      { "type": "elemental", "element": "fire", "value": 10 }
    ]
  },
  "defender": {
    "defense": 20,
    "armor": 15,
    "resistances": { "fire": 0.25, "ice": -0.1 },
    "vulnerabilities": []
  },
  "attackType": "physical",
  "element": "fire",
  "isCritical": false,
  "modifiers": ["backstab", "weakened"]
}

Response:

json
{
  "success": true,
  "data": {
    "baseDamage": 45,
    "elementalDamage": 7,
    "totalDamage": 52,
    "mitigated": 18,
    "finalDamage": 34,
    "breakdown": {
      "weaponRoll": 15,
      "attackBonus": 30,
      "elementalBonus": 7,
      "defenseReduction": -15,
      "armorReduction": -8,
      "resistanceReduction": -3,
      "modifierBonus": 8
    },
    "effects": ["burning"],
    "isCritical": false,
    "isBlocked": false,
    "isDodged": false
  }
}

Physics System#

Simulate Physics#

Run physics simulation on objects.

http
POST /v1/gameplay/physics/simulate
Authorization: Bearer <token>
Content-Type: application/json

{
  "objects": [
    {
      "id": "ball_001",
      "type": "sphere",
      "position": [0, 10, 0],
      "velocity": [5, 0, 0],
      "mass": 1.0,
      "radius": 0.5,
      "material": "rubber",
      "restitution": 0.8,
      "friction": 0.3
    },
    {
      "id": "ground",
      "type": "plane",
      "position": [0, 0, 0],
      "normal": [0, 1, 0],
      "static": true,
      "material": "concrete"
    }
  ],
  "forces": [
    { "type": "gravity", "value": [0, -9.81, 0] },
    { "type": "wind", "value": [2, 0, 1] }
  ],
  "duration": 5.0,
  "timeStep": 0.016,
  "substeps": 4
}

Response:

json
{
  "success": true,
  "data": {
    "frames": [
      {
        "time": 0.0,
        "objects": {
          "ball_001": {
            "position": [0, 10, 0],
            "velocity": [5, 0, 0],
            "rotation": [0, 0, 0, 1]
          }
        }
      },
      {
        "time": 0.016,
        "objects": {
          "ball_001": {
            "position": [0.08, 9.998, 0],
            "velocity": [5, -0.157, 0],
            "rotation": [0, 0, 0, 1]
          }
        }
      }
    ],
    "collisions": [
      {
        "time": 1.43,
        "objectA": "ball_001",
        "objectB": "ground",
        "point": [7.15, 0.5, 0],
        "normal": [0, 1, 0],
        "impulse": 12.5
      }
    ],
    "statistics": {
      "totalFrames": 313,
      "collisionCount": 3,
      "maxVelocity": 14.2
    }
  }
}

Raycast Query#

Perform a raycast for collision detection.

http
POST /v1/gameplay/physics/raycast
Authorization: Bearer <token>
Content-Type: application/json

{
  "origin": [0, 1.5, 0],
  "direction": [1, 0, 0],
  "maxDistance": 100,
  "layers": ["characters", "props", "terrain"],
  "excludeIds": ["player_001"],
  "mode": "all"
}

Response:

json
{
  "success": true,
  "data": {
    "hits": [
      {
        "objectId": "wall_001",
        "point": [5.2, 1.5, 0],
        "normal": [-1, 0, 0],
        "distance": 5.2,
        "layer": "terrain"
      },
      {
        "objectId": "enemy_001",
        "point": [3.1, 1.5, 0],
        "normal": [-1, 0, 0],
        "distance": 3.1,
        "layer": "characters"
      }
    ],
    "count": 2
  }
}

Inventory System#

Create Inventory#

Create a new inventory instance.

http
POST /v1/gameplay/inventory/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "ownerId": "player_001",
  "ownerType": "character",
  "type": "backpack",
  "capacity": {
    "slots": 30,
    "maxWeight": 100
  },
  "restrictions": {
    "allowedCategories": ["weapon", "armor", "consumable", "material"],
    "forbiddenItems": ["quest_key_special"]
  },
  "stackingRules": {
    "consumable": 99,
    "material": 999,
    "default": 1
  }
}

Add Item#

Add an item to inventory.

http
POST /v1/gameplay/inventory/{inventoryId}/add
Authorization: Bearer <token>
Content-Type: application/json

{
  "itemId": "potion_health_large",
  "quantity": 5,
  "slot": null,
  "metadata": {
    "quality": "legendary",
    "enchantments": ["life_steal"]
  }
}

Response:

json
{
  "success": true,
  "data": {
    "added": true,
    "slot": 12,
    "stackId": "stack_abc123",
    "newQuantity": 5,
    "remainingCapacity": {
      "slots": 17,
      "weight": 95.5
    }
  }
}

Transfer Items#

Transfer items between inventories.

http
POST /v1/gameplay/inventory/{inventoryId}/transfer
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetInventoryId": "inv_chest_001",
  "items": [
    { "slot": 5, "quantity": 10 },
    { "slot": 12, "quantity": "all" }
  ],
  "validateCapacity": true
}

Quest System#

Create Quest#

Define a new quest.

http
POST /v1/gameplay/quest/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "quest_dragon_slayer",
  "name": "The Dragon's Bane",
  "description": "Defeat the ancient dragon terrorizing the village",
  "type": "main",
  "level": 25,
  "objectives": [
    {
      "id": "obj_gather_info",
      "type": "talk",
      "description": "Speak with the village elder",
      "target": "npc_elder",
      "required": true
    },
    {
      "id": "obj_find_lair",
      "type": "discover",
      "description": "Find the dragon's lair",
      "target": "location_dragon_lair",
      "required": true,
      "dependsOn": ["obj_gather_info"]
    },
    {
      "id": "obj_slay_dragon",
      "type": "kill",
      "description": "Defeat the Ancient Dragon",
      "target": "creature_ancient_dragon",
      "count": 1,
      "required": true,
      "dependsOn": ["obj_find_lair"]
    },
    {
      "id": "obj_rescue_prisoners",
      "type": "rescue",
      "description": "Rescue captured villagers",
      "target": "villager",
      "count": 5,
      "required": false
    }
  ],
  "rewards": {
    "experience": 5000,
    "gold": 1000,
    "items": ["sword_dragonbane", "dragon_scale_armor"],
    "reputation": { "village": 100, "kingdom": 50 }
  },
  "prerequisites": {
    "level": 20,
    "quests": ["quest_village_defender"],
    "reputation": { "village": 50 }
  },
  "timeLimit": null,
  "repeatable": false
}

Update Quest Progress#

Update objective progress.

http
POST /v1/gameplay/quest/{questId}/update
Authorization: Bearer <token>
Content-Type: application/json

{
  "playerId": "player_001",
  "objectiveId": "obj_rescue_prisoners",
  "action": "increment",
  "value": 2,
  "metadata": {
    "location": "dragon_lair_prison",
    "method": "stealth"
  }
}

Response:

json
{
  "success": true,
  "data": {
    "questId": "quest_dragon_slayer",
    "status": "in_progress",
    "objectives": {
      "obj_gather_info": { "status": "completed", "progress": 1, "target": 1 },
      "obj_find_lair": { "status": "completed", "progress": 1, "target": 1 },
      "obj_slay_dragon": {
        "status": "in_progress",
        "progress": 0,
        "target": 1
      },
      "obj_rescue_prisoners": {
        "status": "in_progress",
        "progress": 3,
        "target": 5
      }
    },
    "completionPercentage": 60,
    "unlockedObjectives": ["obj_slay_dragon"],
    "events": [
      {
        "type": "objective_progress",
        "objective": "obj_rescue_prisoners",
        "progress": 3
      }
    ]
  }
}

Dialogue System#

Generate Dialogue#

Generate contextual dialogue options.

http
POST /v1/gameplay/dialogue/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "npcId": "npc_merchant",
  "playerId": "player_001",
  "context": {
    "location": "market_square",
    "timeOfDay": "afternoon",
    "weather": "sunny",
    "playerReputation": 75,
    "previousInteractions": 5,
    "activeQuests": ["quest_find_artifact"],
    "playerInventory": ["gold:500", "rare_gem"],
    "npcMood": "friendly"
  },
  "conversationHistory": [
    { "speaker": "npc", "text": "Welcome back, friend! Looking for anything special today?" }
  ],
  "style": "medieval_fantasy",
  "maxOptions": 4
}

Response:

json
{
  "success": true,
  "data": {
    "options": [
      {
        "id": "opt_1",
        "text": "I'm looking for information about the ancient artifact.",
        "tone": "inquisitive",
        "skillCheck": null,
        "consequences": { "questProgress": true }
      },
      {
        "id": "opt_2",
        "text": "Show me your finest wares, merchant.",
        "tone": "neutral",
        "skillCheck": null,
        "consequences": { "opensShop": true }
      },
      {
        "id": "opt_3",
        "text": "[Persuade] Perhaps you could offer me a discount, given our history?",
        "tone": "persuasive",
        "skillCheck": { "skill": "persuasion", "difficulty": 15 },
        "consequences": { "discount": 0.15 }
      },
      {
        "id": "opt_4",
        "text": "I'll be on my way. Farewell.",
        "tone": "farewell",
        "skillCheck": null,
        "consequences": { "endsConversation": true }
      }
    ],
    "npcState": {
      "mood": "friendly",
      "disposition": 75,
      "knowsAboutArtifact": true
    }
  }
}

Economy System#

Process Transaction#

Execute an economic transaction.

http
POST /v1/gameplay/economy/transaction
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "purchase",
  "buyerId": "player_001",
  "sellerId": "npc_merchant",
  "items": [
    { "itemId": "potion_health", "quantity": 10, "pricePerUnit": 25 },
    { "itemId": "sword_steel", "quantity": 1, "pricePerUnit": 500 }
  ],
  "currency": "gold",
  "applyDiscounts": true,
  "validateFunds": true
}

Response:

json
{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "completed",
    "subtotal": 750,
    "discounts": [
      { "type": "reputation", "amount": 75, "reason": "Loyal customer" }
    ],
    "taxes": 0,
    "total": 675,
    "buyerBalance": { "before": 1000, "after": 325 },
    "sellerBalance": { "before": 5000, "after": 5675 },
    "itemsTransferred": [
      { "itemId": "potion_health", "quantity": 10 },
      { "itemId": "sword_steel", "quantity": 1 }
    ]
  }
}

Crafting System#

Check Recipe#

Verify crafting recipe requirements.

http
POST /v1/gameplay/crafting/recipe
Authorization: Bearer <token>
Content-Type: application/json

{
  "recipeId": "recipe_sword_enchanted",
  "crafterId": "player_001",
  "checkInventory": true
}

Response:

json
{
  "success": true,
  "data": {
    "recipeId": "recipe_sword_enchanted",
    "name": "Enchanted Steel Sword",
    "canCraft": true,
    "requirements": {
      "level": { "required": 15, "current": 20, "met": true },
      "skill": { "required": 50, "current": 65, "met": true },
      "materials": [
        { "itemId": "steel_ingot", "required": 3, "available": 5, "met": true },
        {
          "itemId": "magic_essence",
          "required": 1,
          "available": 2,
          "met": true
        },
        { "itemId": "leather_grip", "required": 1, "available": 1, "met": true }
      ],
      "tools": [
        { "toolId": "forge", "available": true },
        { "toolId": "enchanting_table", "available": true }
      ]
    },
    "output": {
      "itemId": "sword_enchanted_steel",
      "quantity": 1,
      "quality": "rare"
    },
    "craftingTime": 30,
    "experienceGain": 150
  }
}

Craft Item#

Execute crafting.

http
POST /v1/gameplay/crafting/craft
Authorization: Bearer <token>
Content-Type: application/json

{
  "recipeId": "recipe_sword_enchanted",
  "crafterId": "player_001",
  "quantity": 1,
  "qualityBonus": true
}

Error Codes#

Code Description
INVALID_COMBAT_CONFIG Combat configuration is invalid
INSUFFICIENT_FUNDS Not enough currency
INVENTORY_FULL No inventory space available
QUEST_NOT_FOUND Quest ID does not exist
OBJECTIVE_LOCKED Objective prerequisites not met
RECIPE_REQUIREMENTS_NOT_MET Missing materials or skills
PHYSICS_TIMEOUT Simulation took too long
INVALID_ITEM Item ID does not exist

Rate Limits#

Endpoint Limit
Combat simulation 10/minute
Physics simulation 20/minute
Inventory operations 100/minute
Quest updates 50/minute
Dialogue generation 30/minute
Transactions 50/minute